#12211: clarify math.copysign() documentation and docstring

Doc/library/math.rst

@@ -36,9 +36,12 @@ Number-theoretic and representation functions
 
 .. function:: copysign(x, y)
 
-   Return *x* with the sign of *y*.  On a platform that supports
-   signed zeros, ``copysign(1.0, -0.0)`` returns *-1.0*.
+   Return a float with the magnitude (absolute value) of *x* but the sign of
+   *y*.  On platforms that support signed zeros, ``copysign(1.0, -0.0)``
+   returns *-1.0*.
 
+   If *x* is NaN, *y* is ignored and NaN is returned.  If *y* is NaN,
+   it is treated as positive: ``copysign(-1.0, NaN)`` returns 1.0.
 
 .. function:: fabs(x)
 

Modules/mathmodule.c

@@ -906,7 +906,11 @@ PyDoc_STRVAR(math_ceil_doc,
              "This is the smallest integral value >= x.");
 
 FUNC2(copysign, copysign,
-      "copysign(x, y)\n\nReturn x with the sign of y.")
+      "copysign(x, y)\n\nReturn a float with the magnitude (absolute value) "
+      "of x but the sign \nof y. On platforms that support signed zeros, "
+      "copysign(1.0, -0.0) \nreturns -1.0.\n\n"
+      "If x is NaN, y is ignored and NaN is returned. If y is NaN, it is\n"
+      "treated as positive.")
 FUNC1(cos, cos, 0,
       "cos(x)\n\nReturn the cosine of x (measured in radians).")
 FUNC1(cosh, cosh, 1,