Clarified javadoc of atan2 CalculusFieldElement.

Github fixes #140
Hipparchus-Math · Jun 19, 2021 · 8481d13 · 8481d13
1 parent 5709365
commit 8481d13
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 0 deletions.
diff --git a/hipparchus-core/src/changes/changes.xml b/hipparchus-core/src/changes/changes.xml
@@ -50,6 +50,10 @@ If the output is not quite correct, check for invisible trailing spaces!
   </properties>
   <body>
     <release version="2.0" date="TBD" description="TBD">
+      <action dev="luc" type="fix" issue="issues/140">
+        Clarified arguments in the one-argument version of the two-arguments atan2
+        function in CalculusFieldElement.
+      </action>
       <action dev="luc" type="fix" issue="issues/138">
         Renamed signum into sign in field classes, and improved implementation for complex numbers.
       </action>

diff --git a/hipparchus-core/src/main/java/org/hipparchus/CalculusFieldElement.java b/hipparchus-core/src/main/java/org/hipparchus/CalculusFieldElement.java
@@ -216,6 +216,19 @@ T pow(T e)
     T atan();
 
     /** Two arguments arc tangent operation.
+     * <p>
+     * Beware of the order or arguments! As this is based on a
+     * two-arguments functions, in order to be consistent with
+     * arguments order, the instance is the <em>first</em> argument
+     * and the single provided argument is the <em>second</em> argument.
+     * In order to be consistent with programming languages {@code atan2},
+     * this method computes {@code atan2(this, x)}, i.e. the instance
+     * represents the {@code y} argument and the {@code x} argument is
+     * the one passed as a single argument. This may seem confusing especially
+     * for users of Wolfram alpha, as this site is <em>not</em> consistent
+     * with programming languages {@code atan2} two-arguments arc tangent
+     * and puts {@code x} as its first argument.
+     * </p>
      * @param x second argument of the arc tangent
      * @return atan2(this, x)
      * @exception MathIllegalArgumentException if number of free parameters or orders are inconsistent

diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -50,6 +50,10 @@ If the output is not quite correct, check for invisible trailing spaces!
   </properties>
   <body>
     <release version="2.0" date="TBD" description="TBD">
+      <action dev="luc" type="fix" issue="issues/140">
+        Clarified arguments in the one-argument version of the two-arguments atan2
+        function in CalculusFieldElement.
+      </action>
       <action dev="luc" type="fix" issue="issues/138">
         Renamed signum into sign in field classes, and improved implementation for complex numbers.
       </action>