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

 
 

bug #46821: cumsum: output variables not documented

Submitted by:  Pantxo Diribarne <pantxo>
Submitted on:  Tue 05 Jan 2016 04:14:45 PM UTC  
 
Category: DocumentationSeverity: 3 - Normal
Priority: 5 - NormalItem Group: Documentation
Status: FixedAssigned to: None
Originator Name: Open/Closed: Closed
Release: 4.0.0Operating 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)

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>
Project 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>
Project 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>
Project 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:

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>
Project 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>
Project 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>
Project 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>
Project 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>
Project Member
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>
Project Member

 

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

Attach File(s):
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

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

    Date Changed By Updated Field Previous Value => Replaced By
    Tue 12 Jan 2016 06:29:20 PM UTCrik5StatusConfirmed=>Fixed
      Open/ClosedOpen=>Closed
    Mon 11 Jan 2016 06:35:39 PM UTCjweCarbon-Copy-=>Added rik5
    Wed 06 Jan 2016 03:26:44 PM UTCpantxoStatusNone=>Confirmed

    Back to the top


    Powered by Savane 3.1-cleanup1