docstrings in the reference manual

docstrings in the reference manual

[jamil egdemir]

Hi,

I'm almost afraid to ask this one but I've been poking around the
reference manual at:

https://www.gnu.org/software/guile/manual/html_node/index.html

for a while now and for the life of me I can't find a description of
how docstrings work in guile.  When I say docstring here I'm thinking
of docstrings like we have in python.  Googling for 'docstrings guile
scheme site:www.gnu.org/software/guile' is showing hits under function
snarfing here:

https://www.gnu.org/software/guile/manual/html_node/Function-Snarfing.html

but when I look there it seems related to coding up new built-ins
using C.  I'm very new to guile but I was under the impression that
docstrings were more like the notion of docstring in python as
described here:

https://www.python.org/dev/peps/pep-0257/

Apologies in advance if I'm missing something obvious in the ref
manual here again.  :)

-j

-- 
-------------------------------------------------------------
Jamil Egdemir
unclejamil@gmail.com
http://www.power-quant.com
(631) 338-3170 (cell)
-------------------------------------------------------------

Re: docstrings in the reference manual

[Panicz Maciej Godek]

[-- Attachment #1: Type: text/plain, Size: 1128 bytes --]

Hello jamil

2014-12-15 23:48 GMT+01:00 jamil egdemir <unclejamil@gmail.com>:
>
> Hi,
>
> I'm almost afraid to ask this one but I've been poking around the
> reference manual at:
>
> https://www.gnu.org/software/guile/manual/html_node/index.html
>
> for a while now and for the life of me I can't find a description of
> how docstrings work in guile.  When I say docstring here I'm thinking
> of docstrings like we have in python.


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.

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.

[-- Attachment #2: Type: text/html, Size: 1914 bytes --]

Re: docstrings in the reference manual

[jamil egdemir]

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
-------------------------------------------------------------

Re: docstrings in the reference manual

[Panicz Maciej Godek]

[-- Attachment #1: Type: text/plain, Size: 1123 bytes --]

>
>
> > 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.
>
>
I think it is an acceptable solution, although I also think that the Guile
team would prefer a patch (to guile-devel) that could be pushed directly to
the git repo (OTOH, one needs to know at least the basic syntax of texinfo
to make sure that the "docstring" node appears in the concept index)

A bug report should be sufficient, though, especially if the improvemet
suggestions are clear enough

[-- Attachment #2: Type: text/html, Size: 1635 bytes --]

Re: docstrings in the reference manual

[John Darrington]

[-- 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 --]

Re: docstrings in the reference manual

[Panicz Maciej Godek]

[-- Attachment #1: Type: text/plain, Size: 1077 bytes --]

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.
>
>
Actually, there's a wikipedia entry regarding that notion:
http://en.wikipedia.org/wiki/Docstring
It appears that the word 'docstring' is already used in the technical
jargon and Jamil's case proves that the manual could do better in
faciliating the search.

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


If you take a look at the index of the manual, you'll find entries like:
"alist", "async", "errno", "smob", "vcell" and so on. I don't think that
adding a "docstring" entry would do any harm in this particular context (on
the other hand, the "documentation string" entry is lacking as well, so I
agree that it is more important to add this one in the first place)

[-- Attachment #2: Type: text/html, Size: 1907 bytes --]

Re: docstrings in the reference manual

[jamil egdemir]

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
-------------------------------------------------------------