Merge pull request #3761 from w3c/AmeliaBR-patch-trig

[css-values-4] Clean up trig function definitions

Author: tabatkins

css-values-4/Overview.bs

@@ -2472,13 +2472,13 @@ Trigonometric Functions: ''sin()'', ''cos()'', ''tan()'', ''asin()'', ''acos()''
 	''sin()'', ''cos()'', ''tan()'', ''asin()'', ''acos()'', ''atan()'', and ''atan2()''--
 	compute the various basic trigonometric relationships.
 
-	The <dfn lt="sin()">sin(A)</dfn>, <dfn lt="cos(A)">cos()</dfn>, and <dfn lt="tan()">tan(A)</dfn> functions
+	The <dfn lt="sin()">sin(A)</dfn>, <dfn lt="cos()">cos(A)</dfn>, and <dfn lt="tan()">tan(A)</dfn> functions
 	all contain a single [=calculation=]
 	which must resolve to either a <<number>>
 	or an <<angle>>,
 	and compute their corresponding function
 	by interpreting the result of their argument as radians.
-	(That is, ''sin(45deg)'', ''sin(.125)'', and ''sin(3.14159 / 4 * 1rad)''
+	(That is, ''sin(45deg)'', ''sin(.125turn)'', and ''sin(3.14159 / 4)''
 	all represent the same value,
 	approximately ''.707''.)
 	They all represent a <<number>>;
@@ -2499,21 +2499,23 @@ Trigonometric Functions: ''sin()'', ''cos()'', ''tan()'', ''asin()'', ''acos()''
 	and the angle returned by ''atan()'' to the range [''-90deg'', ''90deg''].
 
 	The <dfn lt="atan2()">atan2(A, B)</dfn> function
-	contains two comma-separated [=calculations=] A and B
-	that must resolve to <<number>>s,
-	and returns the <<angle>>
+	contains two comma-separated [=calculations=], A and B.
+	A and B can resolve to any <<number>>, <<dimension>>, or <<percentage>>,
+	but must have the <em>same</em> [=determine the type of a calculation|type=],
+	or else the function is invalid.
+	The function returns the <<angle>>
 	between the positive X-axis and the point (B,A).
 	The returned angle must be normalized to the interval (''-180deg'', ''180deg'']
 	(that is, greater than ''-180deg'', and less than or equal to ''180deg'').
 
 	Note: ''atan2(Y, X)'' is <em>generally</em> equivalent to ''atan(Y / X)'',
-	but it gives a better answer when the point in question is in the second (NW) or third (SW) quadrants of the plane.
-	''atan2(1, -1)'', corresponding to the point (-1, 1) in the NW of the plane,
+	but it gives a better answer when the point in question may include negative components.
+	''atan2(1, -1)'', corresponding to the point (-1, 1),
 	returns ''135deg'',
-	distinct from ''atan2(-1, 1)'', corresponding to the point (1, -1) in the SE of the plane,
+	distinct from ''atan2(-1, 1)'', corresponding to the point (1, -1),
 	which returns ''-45deg''.
-	However, as ''1 / -1'' and ''-1 / 1'' both resolve to ''-1'',
-	''atan()'' returns the same ''-45deg'' for both points.
+	In contrast, ''atan(1 / -1)'' and ''atan(-1 / 1)'' both return''-45deg'',
+	because the internal calculation resolves to ''-1'' for both.
 
 
 <h4 id="trig-infinities">
@@ -2603,6 +2605,7 @@ Exponential  Functions: ''pow()'', ''sqrt()'', ''hypot()''</h3>
 		and then the ''pow(X, 1/3)'' would cube-root the value back down to 30 and multiply the exponent by 1/3,
 		giving «[ "length" → 1 ]»,
 		which [=CSSNumericValue/matches=] <<length>>.
+
 		In the realm of pure mathematics, that's guaranteed to work out;
 		in the real-world of computers using binary floating-point arithmetic,
 		in some cases the powers might not exactly cancel out,
@@ -2652,7 +2655,8 @@ Exponential  Functions: ''pow()'', ''sqrt()'', ''hypot()''</h3>
 		as the inputs and output all have the same type.
 		The result isn't unit-dependent, either,
 		due to the nature of the operation;
-		''hypot(3em, 4em)'' and ''hypot(48px, 64px)'' give the same result in both cases:
+		''hypot(3em, 4em)'' and ''hypot(48px, 64px)'' both result in the same length
+		when ''1em'' equals ''16px'':
 		''5em'' or ''80px''.
 		Thus it's fine to let author use dimensions directly in ''hypot()''.
 	</details>
@@ -2986,14 +2990,14 @@ Computed Value</h3>
 		so implementations can simplify the expressions
 		further than what is required here
 		when storing the values internally;
-		in particular, all [=math function=] expressions can be reduced
+		in particular, all [=calculation=] expressions can be reduced
 		to a sum of a <<number>>, a <<percentage>>, and some <<dimension>>s,
 		eliminating all multiplication or division,
 		and combining terms with identical units.
 
 		At this time, all units can be absolutized
 		to a single unit per type at computed-value time,
-		so at that point the [=math function=] can be reduced
+		so at that point the [=calculation=] can be reduced
 		to just a <<number>>, a <<percentage>>, and a single absolute <<dimension>> of the appropriate type,
 		per expression.
 	</div>