bugGNU Octave - Bugs: bug #46821, cumsum: output variables not...

 
 

bug #46821: cumsum: output variables not documented

Submitter:  Pantxo Diribarne <pantxo>
Submitted:  Tue 05 Jan 2016 04:14:45 PM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * 4.0.0 Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Tue 12 Jan 2016 06:29:20 PM UTC, comment #8: 

I fixed the typo here (http://hg.savannah.gnu.org/hgweb/octave/rev/12e98e5ebd13).  Closing report.

Rik <rik5>
Group administrator
Tue 12 Jan 2016 09:51:10 AM UTC, comment #7: 

Ok, I didn't notice that cumsum was not the only function for which we didn't mention the output variable and indeed it would be hard work. So lets forget about it and close this report once the typo is fixed.

Pantxo Diribarne <pantxo>
Group Member
Mon 11 Jan 2016 09:22:51 PM UTC, comment #6: 

Adding a return variable declaration to the documentation for functions which return only a single variable would, arguably, be slightly clearer.  Not that we have to be slavish to Matlab, but this is what they do.

On the other hand, I do agree with jwe that it clutters the documentation.  I think, most importantly, is that this is opposite to the convention we have been using.  Rather than have this one docstring be different from the rest, I would code it without the return variable.

If we want to change the documentation over to universally have a return value we should do so in just one changeset.  This should only be after discussion on the Maintainer's list.  Right now I would probably vote against changing it because it means a lot of work, for a small gain.  If someone has 8 hours to work on Octave, I can see other projects that I would have them do first.



Rik <rik5>
Group administrator
Mon 11 Jan 2016 06:35:39 PM UTC, comment #5: 

Oops, that was a cut and paste error.

When a function returns a single value, we don't normally write that in the docstring.  I don't particularly like the idea of cluttering up all the docstrings with things like this:


  y = sin (x)
  y = sqrt (x)
  y = exp (x)
  ...


Rik, what do you think?  I'm adding you here since you've done a lot of work to make the style of the docstrings more consistent.

John W. Eaton <jwe>
Group administrator
Mon 11 Jan 2016 03:05:05 PM UTC, comment #4: 

@jwe: yes an example is often better than an explanation (even by native english). I noticed a typo, "cumsum" should be "cumprod" in cumprod's example. Also, why not add "y = cumsum (x)" instead of just "cumsum (x)" in the header to make it clear at first sight that the function actually returns a variable.

Pantxo Diribarne <pantxo>
Group Member
Fri 08 Jan 2016 04:45:42 PM UTC, comment #3: 

I added examples to the cumsum and cumprod docstrings in this changeset:

http://hg.savannah.gnu.org/hgweb/octave/rev/8190fe6dc3fd

Is that enough to make it clear what these functions do?

John W. Eaton <jwe>
Group administrator
Wed 06 Jan 2016 03:26:44 PM UTC, comment #2: 

I have no time right now but I can do it at some point for cumsum and cumprod if no one does (native English welcome for documentation:-)).

Pantxo Diribarne <pantxo>
Group Member
Wed 06 Jan 2016 01:50:40 AM UTC, comment #1: 

Could you please write some documentation?

I think it pretty much follows the behaviour of Matlab's cumsum (but we can't just copy their documentation).

Lachlan Andrew <lachlan>
Tue 05 Jan 2016 04:14:45 PM UTC, original submission:  

The title says it all. There is no mention in the documentation of the output variable and its shape depending on input argument.

Pantxo Diribarne <pantxo>
Group Member

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by jwe
  • -email is unavailable- added by jwe (Posted a comment)
  • -email is unavailable- added by lachlan (Posted a comment)
  • -email is unavailable- added by pantxo (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 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2016-01-12 rik5 StatusConfirmed Fixed
        Open/ClosedOpen Closed
    2016-01-11 jwe Carbon-Copy- Added rik5
    2016-01-06 pantxo StatusNone Confirmed

    Back to the top

    Powered by Savane 3.13-d3ae.
    Corresponding source code