From: John Darrington <john@darrington.wattle.id.au>
To: jamil egdemir <unclejamil@gmail.com>
Cc: guile-user <guile-user@gnu.org>
Subject: Re: docstrings in the reference manual
Date: Tue, 16 Dec 2014 12:42:48 +0100 [thread overview]
Message-ID: <20141216114248.GA4960@intra> (raw)
In-Reply-To: <CAOa+0os-KB_5GnYeHW9Q7Wq0P7G-Ac5mcTqcoGqd7yvnRLmxtg@mail.gmail.com>
[-- Attachment #1: Type: text/plain, Size: 2221 bytes --]
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 <godek.maciek@gmail.com> 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
unclejamil@gmail.com
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.
[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]
next prev parent reply other threads:[~2014-12-16 11:42 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-12-15 22:48 docstrings in the reference manual jamil egdemir
2014-12-16 6:50 ` Panicz Maciej Godek
2014-12-16 10:54 ` jamil egdemir
2014-12-16 11:41 ` Panicz Maciej Godek
2014-12-16 11:42 ` John Darrington [this message]
2014-12-16 12:18 ` Panicz Maciej Godek
2014-12-16 20:16 ` jamil egdemir
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20141216114248.GA4960@intra \
--to=john@darrington.wattle.id.au \
--cc=guile-user@gnu.org \
--cc=unclejamil@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).