[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: docstrings in the reference manual
From: |
John Darrington |
Subject: |
Re: docstrings in the reference manual |
Date: |
Tue, 16 Dec 2014 12:42:48 +0100 |
User-agent: |
Mutt/1.5.21 (2010-09-15) |
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