Re: docstrings in the reference manual

[jamil egdemir]

John,

> 2014-12-16 12:42 GMT+01:00 John Darrington <address@hidden>:
>>
>> 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
address@hidden
http://www.power-quant.com
-------------------------------------------------------------