[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/
- [Octave-bug-tracker] [bug #53388] doc: first sentence of some doc strings too long or not structured consistently,
Mike Miller <=