From: jamil egdemir <unclejamil@gmail.com>
To: guile-user <guile-user@gnu.org>
Subject: Re: docstrings in the reference manual
Date: Tue, 16 Dec 2014 15:16:55 -0500 [thread overview]
Message-ID: <CAOa+0otvQhy9hDOJkk8w2RT=+2TsNTr38FCha3mMYxP2JvZpwQ@mail.gmail.com> (raw)
In-Reply-To: <CAMFYt2YsRp=iJ_TFTeJfkMX5Au6wgX_pYdHg7Th8PNb-B-qPVA@mail.gmail.com>
John,
> 2014-12-16 12:42 GMT+01:00 John Darrington <john@darrington.wattle.id.au>:
>>
>> 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.
You have made some good points. I guess I'd add a couple more:
- The word docstrings is already in use in the reference manual in at
least one place:
https://www.gnu.org/software/guile/manual/html_node/Function-Snarfing.html
- Anyone coming to scheme (at least) from Python is likely to
eventually look for docstrings in the index. At one point last night
I did and ended up searching through the larger html version of the
ref manual on one page for 'docstring' and ended up in the section on
function snarfing (mentioned above). That section wasn't quite what I
was looking for though it seemed related so I then backed off and
searched for 'doc'. This resulted in jillions of hits. Unfortunately
I gave up before finding the passage Panicz pointed out. Perhaps
'docstring' has cropped up b/c the word documentation is used so
frequently in ref manuals like this that it camouflauges any
description of the docstring concept. I'm no expert on these things
but perhaps 'docstring' has popped into existence for this reason.
-j
--
-------------------------------------------------------------
Jamil Egdemir
unclejamil@gmail.com
http://www.power-quant.com
-------------------------------------------------------------
prev parent reply other threads:[~2014-12-16 20:16 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
2014-12-16 12:18 ` Panicz Maciej Godek
2014-12-16 20:16 ` jamil egdemir [this message]
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='CAOa+0otvQhy9hDOJkk8w2RT=+2TsNTr38FCha3mMYxP2JvZpwQ@mail.gmail.com' \
--to=unclejamil@gmail.com \
--cc=guile-user@gnu.org \
/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).