Bug 123192 - Improve help for function ATAN2
Summary: Improve help for function ATAN2
Status: RESOLVED FIXED
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Documentation (show other bugs)
Version:
(earliest affected)
6.3.0.0.alpha0+
Hardware: x86-64 (AMD64) Windows (All)
: medium enhancement
Assignee: Mark
URL:
Whiteboard: target:6.3.0
Keywords: easyHack
Depends on:
Blocks: HelpGaps-NewFeatures
  Show dependency treegraph
 
Reported: 2019-02-05 15:13 UTC by Regina Henschel
Modified: 2019-03-28 14:50 UTC (History)
4 users (show)

See Also:
Crash report or crash signature:
Regression By:


Attachments
Illustration as svg (12.18 KB, image/svg+xml)
2019-02-13 20:42 UTC, Regina Henschel
Details
source of Illustration (13.22 KB, application/vnd.oasis.opendocument.graphics)
2019-02-13 20:48 UTC, Regina Henschel
Details

Note You need to log in before you can comment on or make changes to this bug.
Description Regina Henschel 2019-02-05 15:13:04 UTC
The ATAN2 function in Calc has the syntax
ATAN2(NumberX; NumberY)

Unfortunately that is the opposite order of arguments as usual in programming language, e.g. Python, JavaScript, C++.
So there should be a warning about this fact. It could be something like this, "Programming languages have usually the opposite order of arguments for their atan2 function."

In this light, the given example is badly chosen, because both parameters have the same value 20 in the example. And using a point from the first quadrant, masks the advantage over using ATAN(NumberY/NumberX).
The example should use a point from the second quadrant, e.g. point(-5|9).

The help says "Returns the inverse trigonometric tangent of the specified x and y coordinates.". That makes no mathematical sense, remove it. Suggestion: "ATAN2 returns the angle (in radians) between the x-axis and a line from the origin to the point (NumberX|NumberY)".

The text "To return the angle in degrees, use the DEGREES function." is misleading, because it sounds as if DEGREES would be a similar function as ATAN2, only that the result is in degrees. The example has it correct. It should be something like this, "To get the angle in degrees apply the DEGREES function to the result."

The spec has the text, "ATAN2(0;0) is implementation-defined, evaluators may return 0 or an Error.". The help is missing, what LibreOffice does. In fact, LibreOffice results 0 for ATAN2(0;0). But Excel 365 results error #DIV/0! for  ATAN2(0;0). Therefore it should be mentioned.

The help should mention, that the function can be used in converting cartesian coordinates to polar coordinates.

An illustration would be helpful.
Comment 1 Olivier Hallot 2019-02-05 17:25:49 UTC
Set to New.

Target help page:

https://help.libreoffice.org/6.3/en-US/text/scalc/01/04060106.html?DbPAR=CALC#bm_id3153983
Comment 2 Regina Henschel 2019-02-13 20:42:17 UTC
Created attachment 149281 [details]
Illustration as svg
Comment 3 Regina Henschel 2019-02-13 20:48:43 UTC
Created attachment 149282 [details]
source of Illustration

Hi Mark, that is my version of an illustration. You might want to alter it or make your own one. Please do not use LibreOffice to generate an svg-image. Since LibreOffice has changed the svg export for the benefit of Impress, it generates horrible svg source in case of Draw. You get much cleaner svg source if you use Apache OpenOffice which still has the old svg export for Draw.
Comment 4 Commit Notification 2019-02-25 16:30:15 UTC
Mark committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/+/3efabd3e5e7ac30a81de5f286f6c9c5a3327effb%5E%21

tdf#123192 - Improve help for function ATAN2
Comment 5 Xisco Faulí 2019-03-28 04:17:53 UTC
A polite ping, still working on this bug?