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

 
 

bug #48178: atan2 docstring needs more detail

Submitted by:  Marco Caliari <caliari>
Submitted on:  Wed 08 Jun 2016 03:10:46 PM UTC  
 
Category: DocumentationSeverity: 2 - Minor
Priority: 3 - LowItem Group: Feature Request
Status: FixedAssigned to: None
Originator Name: Open/Closed: Closed
Release: 4.0.2Operating System: Any

Add a New Comment(Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

(Jump to the original submission 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>
Project Administrator
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>
Project Member
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>
Project Administrator
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>
Project Member
Wed 08 Jun 2016 06:16:02 PM UTC, comment #2:

How about the attached doc patch.

(file #37434)

Mike Miller <mtmiller>
Project Administrator
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>
Project Administrator
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>
Project Member

 

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

Attach File(s):
   
   
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
  • -unavailable- added by lachlan (Posted a comment)
  • -unavailable- added by mtmiller (Posted a comment)
  • -unavailable- added by caliari (Submitted the item)
  •  

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only project members can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    Follow 11 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Fri 17 Jun 2016 09:57:12 PM UTCmtmillerOpen/ClosedOpen=>Closed
    Fri 17 Jun 2016 09:57:11 PM UTCmtmillerStatusPatch Submitted=>Fixed
    Wed 08 Jun 2016 06:16:20 PM UTCmtmillerPriority5 - Normal=>3 - Low
      StatusConfirmed=>Patch Submitted
      Release4.0.0=>4.0.2
      Operating SystemGNU/Linux=>Any
    Wed 08 Jun 2016 06:16:02 PM UTCmtmillerAttached File-=>Added atan2.diff, #37434
    Wed 08 Jun 2016 06:02:05 PM UTCmtmillerSeverity3 - 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.1-cleanup1