bugGNU Octave - Bugs: bug #48178, atan2 docstring needs more detail

 
 

bug #48178: atan2 docstring needs more detail

Submitter:  Marco Caliari <caliari>
Submitted:  Wed 08 Jun 2016 03:10:46 PM UTC
   
 
Category:  Documentation Severity:  2 - Minor
Priority:  3 - Low Item Group:  Feature Request
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * 4.0.2 Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Fri 17 Jun 2016 09:57:12 PM UTC, comment #6: 

Applied on the stable branch and merged to default, thanks for discussion and feedback all

http://hg.savannah.gnu.org/hgweb/octave/rev/9780323c1c89

Lachlan, I do see your point about breaking docstrings on newlines for maintainability, but I stuck to the style we have in there for now. If desired someone can go through and change all of the docstrings in a batch, that would be easier to handle than just one oddball.

Mike Miller <mtmiller>
Group Member
Fri 17 Jun 2016 02:37:01 AM UTC, comment #5: 

I think the text of Mike's patch is clear enough.

One tiny nit is that I'd suggest starting the new sentence on a new line, as discussed at  http://octave.1599824.n4.nabble.com/Line-length-for-code-tc4674493.html.  It makes VCS entries cleaner.

Lachlan Andrew <lachlan>
Thu 09 Jun 2016 03:32:38 PM UTC, comment #4: 

I find that even more confusing than the present ambiguity. And the summary line should be short and straightforward. More detail in the body of the docstring. I think it is that way now.

Adding a bit about atan2(0,0) seems overly specific and redundant given my change to show that it is equivalent to arg(complex(0,0)).

Mike Miller <mtmiller>
Group Member
Thu 09 Jun 2016 07:05:28 AM UTC, comment #3: 

What about

Compute atan (@var{y} / @var{x}) +/- pi for...

instead. And a final

atan (0, 0) is defined as 0.

Marco Caliari <caliari>
Group Member
Wed 08 Jun 2016 06:16:02 PM UTC, comment #2: 

How about the attached doc patch.

(file #37434)

Mike Miller <mtmiller>
Group Member
Wed 08 Jun 2016 06:02:05 PM UTC, comment #1: 

True, some detail is missing here. Having a definition that depends on `arg` may be ok, but `arg` also defines itself in terms of `atan2`, so a little circular and maybe not clear to the beginner.

Some sample wordings from standard libraries might help inspire a way to be clearer here.

POSIX:

> These functions shall compute the principal value of the arc
> tangent of y/x, using the signs of both arguments to determine
> the quadrant of the return value.


C11:

> The atan2 functions compute the value of the arc tangent of
> y/x, using the signs of both arguments to determine the
> quadrant of the return value.


Cppreference.com:

> Computes the arc tangent of y/x using the signs of arguments
> to determine the correct quadrant.



Mike Miller <mtmiller>
Group Member
Wed 08 Jun 2016 03:10:46 PM UTC, original submission:  

This is somehow related to #37379. Anyway, the definition of atan2 can be found in wikipedia, with the exception that Octave's atan2(0,0) = 0. Another possibility is to say that atan2(y,x)=arg(x+1i*y). For sure, it is not (always) atan (y / x) (try atan2(-1,-1), atan(1)).

Marco Caliari <caliari>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #37434:  atan2.diff added by mtmiller (644B - text/x-diff)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by lachlan (Posted a comment)
  • -email is unavailable- added by mtmiller (Posted a comment)
  • -email is unavailable- added by caliari (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follow 11 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2016-06-17 mtmiller Open/ClosedOpen Closed
    2016-06-17 mtmiller StatusPatch Submitted Fixed
    2016-06-08 mtmiller Priority5 - Normal 3 - Low
        StatusConfirmed Patch Submitted
        Release4.0.0 4.0.2
        Operating SystemGNU/Linux Any
    2016-06-08 mtmiller Attached File- Added atan2.diff, #37434
    2016-06-08 mtmiller Severity3 - Normal 2 - Minor
        Item GroupNone Feature Request
        StatusNone Confirmed
        Summaryatan2 documentation is wrong atan2 docstring needs more detail

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code