Re: docstrings in the reference manual

[John Darrington]

Why murder the English language more than necessary?  "Docstrings" is a cliche 
which has come from other projects.  Peope for whom English is not their first 
language can be confused by such aliterations.  They won't find the word in any
dictionary.

Write the term "documentation string" out in full, or simply "documentation" 
where the context is clear.

J'

On Tue, Dec 16, 2014 at 05:54:28AM -0500, jamil egdemir wrote:
     Panicz,
     
     On 12/16/14, Panicz Maciej Godek <address@hidden> wrote:
     > It is described here:
     > 
https://www.gnu.org/software/guile/manual/html_node/Procedure-Properties.html
     > (the "procedure-documentation" entry):
     >
     >      Return the documentation string associated with `proc'.  By
     >      convention, if a procedure contains more than one expression and
     >      the first expression is a string constant, that string is assumed
     >      to contain documentation for that procedure.
     
     Good eyes!
     
     > I agree though that it can be difficult to find, and it would be a bit
     > better if it used the word "docstring" (like "that string is assumed to
     > contain documentation for that procedure (so-called 'docstring')"), to 
make
     > it easier to find, and that there should be a "docstring" index entry as
     > well.
     
     I agree.  This info on docstrings is tucked away pretty well.  I
     noticed here in the ref man:
     
     
https://www.gnu.org/software/guile/manual/html_node/Reporting-Bugs.html#Reporting-Bugs
     
     that documentation that is unclear is considered a bug (last bullet in
     the first list).  If you think it makes sense then I'll submit a bug
     on the documentation with this info and your suggestion.
     
     -j
     
     -- 
     -------------------------------------------------------------
     Jamil Egdemir
     address@hidden
     http://www.power-quant.com
     -------------------------------------------------------------

-- 
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See http://sks-keyservers.net or any PGP keyserver for public key.

signature.asc
Description: Digital signature