bugGNU Octave - Bugs: bug #53388, doc: first sentence of some doc...

 
 

bug #53388: doc: first sentence of some doc strings too long or not structured consistently

Submitter:  Mike Miller <mtmiller>
Submitted:  Tue 20 Mar 2018 01:04:24 AM UTC
   
 
Category:  Documentation Severity:  2 - Minor
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * dev Operating System:  * GNU/Linux
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Wed 04 Apr 2018 03:36:01 PM UTC, comment #6: 

Fixed, closing report.

Rik <rik5>
Group administrator
Wed 04 Apr 2018 10:58:30 AM UTC, comment #5: 

I took care of the list in comment #4 plus the other related W.. and O_.. constants in syscalls.cc:

http://hg.savannah.gnu.org/hgweb/octave/rev/476fc012d09a

OK to close now?

John W. Eaton <jwe>
Group administrator
Wed 04 Apr 2018 04:38:19 AM UTC, comment #4: 

I took care of a lot of these (http://hg.savannah.gnu.org/hgweb/octave/rev/d7ad543255c5), but this smaller list of 9 functions remains:

  • WUNTRACED
  • cholinsert
  • cholshift
  • ode15i
  • ode15s
  • qrdelete
  • qrinsert
  • qrshift
  • qrupdate


Rik <rik5>
Group administrator
Thu 29 Mar 2018 04:55:25 AM UTC, comment #3: 

I wasn't working on this bug, but I separately redid the documentation for SEEK_SET (http://hg.savannah.gnu.org/hgweb/octave/rev/db1e3f3664f4) and tic/toc (http://hg.savannah.gnu.org/hgweb/octave/rev/66c35303d272) which resolves the issues mentioned here.

Rik <rik5>
Group administrator
Wed 21 Mar 2018 12:24:59 AM UTC, comment #2: 

I agree.  The first sentence should not simply lead in to a long equation.  And it should be simple enough to use the pattern you suggest.

Rik <rik5>
Group administrator
Tue 20 Mar 2018 01:44:42 AM UTC, comment #1: 

I have taken care of the simple cases (ferror, intersect, rectangle, svds, and zscore) with

https://hg.savannah.gnu.org/hgweb/octave/rev/e178a73af18e
https://hg.savannah.gnu.org/hgweb/octave/rev/75a748cb08a6

Mike Miller <mtmiller>
Group Member
Tue 20 Mar 2018 01:04:24 AM UTC, original submission:  

By convention, the first sentence of the doc string for an Octave function should be short (less than some number of columns?) and typically describes the action that the function performs concisely. Here are some lists of Octave functions that could use some writing work on the first sentences of their doc strings.

These functions have a short enough doc string, but don't end in a period.

  • ferror
  • zscore


These functions start simply enough, but the first sentence leads into a block equation

  • bessel
  • bincoeff
  • daspk
  • dasrt
  • dassl
  • expint
  • gsvd
  • krylov
  • moment
  • qz
  • svd
  • sylvester


It would be helpful to rewrite these with some pattern like


Compute the foo of bar.

The foo of bar is given by

    block equation


The function 'arch_test' needs to be rewritten so the first line summary is useful, using a pattern more like the above functions.

The function 'SEEK_SET' is similar to the above, but the first sentence leads into a table of enumerated types rather than a mathematical formula.

The function 'toc' does not have a doc string at all, it just says "See also: tic, cputime."

These functions have a doc string that starts with an exceptionally long first sentence (more than 200 characters). These should be rewritten with a much more concise first sentence.

  • WUNTRACED
  • bsxfun
  • cholinsert
  • cholshift
  • errno
  • octave_core_file_limit
  • ode15i
  • ode15s
  • qrdelete
  • qrinsert
  • qrshift
  • qrupdate


Lastly, these functions have '@seealso' sections that are not indented properly in the Texinfo formatted text output.

  • intersect
  • rectangle
  • svds
Mike Miller <mtmiller>
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 jwe (Posted a comment)
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by mtmiller (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 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2018-04-04 rik5 StatusConfirmed Fixed
        Open/ClosedOpen Closed
    2018-03-21 rik5 StatusNone Confirmed

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code