octave-bug-tracker
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Octave-bug-tracker] [bug #53388] doc: first sentence of some doc string


From: Mike Miller
Subject: [Octave-bug-tracker] [bug #53388] doc: first sentence of some doc strings too long or not structured consistently
Date: Mon, 19 Mar 2018 21:04:25 -0400 (EDT)
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:59.0) Gecko/20100101 Firefox/59.0

URL:
  <http://savannah.gnu.org/bugs/?53388>

                 Summary: doc: first sentence of some doc strings too long or
not structured consistently
                 Project: GNU Octave
            Submitted by: mtmiller
            Submitted on: Mon 19 Mar 2018 06:04:24 PM PDT
                Category: Documentation
                Severity: 2 - Minor
                Priority: 5 - Normal
              Item Group: Documentation
                  Status: None
             Assigned to: None
         Originator Name: 
        Originator Email: 
             Open/Closed: Open
         Discussion Lock: Any
                 Release: dev
        Operating System: GNU/Linux

    _______________________________________________________

Details:

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




    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?53388>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/




reply via email to

[Prev in Thread] Current Thread [Next in Thread]