procedure docstrings / documentation

procedure docstrings / documentation

[Christopher Howard]

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

Is there any convention on content/formatting for a procedure
docstring? E.g., should I repeat the procedure name and arguments?
Should I insert newlines to maintain a certain text width?

I'm not really clear on how document is done in Guile, overall. I see
Gieser has ways to look up documention for some procedures/modules, but
it doesn't seem to pull that information from the docstring, at least
not my docstrings.

-- 
https://qlfiles.net
https://emailselfdefense.fsf.org/en/

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: procedure docstrings / documentation

[Christopher Howard]

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

No thoughts related to this subject?

On Wed, 2017-09-20 at 16:18 -0800, Christopher Howard wrote:
> Is there any convention on content/formatting for a procedure
> docstring? E.g., should I repeat the procedure name and arguments?
> Should I insert newlines to maintain a certain text width?
> 
> I'm not really clear on how document is done in Guile, overall. I see
> Gieser has ways to look up documention for some procedures/modules,
> but
> it doesn't seem to pull that information from the docstring, at least
> not my docstrings.
> 
-- 
https://qlfiles.net
https://emailselfdefense.fsf.org/en/

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: procedure docstrings / documentation

[Matt Wette]

> On Sep 23, 2017, at 1:56 PM, Christopher Howard <christopher.howard@qlfiles.net> wrote:
> 
> No thoughts related to this subject?
> 
> On Wed, 2017-09-20 at 16:18 -0800, Christopher Howard wrote:
>> Is there any convention on content/formatting for a procedure
>> docstring? E.g., should I repeat the procedure name and arguments?
>> Should I insert newlines to maintain a certain text width?
>> 
>> I'm not really clear on how document is done in Guile, overall. I see
>> Gieser has ways to look up documention for some procedures/modules,
>> but
>> it doesn't seem to pull that information from the docstring, at least
>> not my docstrings.
>> 
> -- 
> https://qlfiles.net
> https://emailselfdefense.fsf.org/en/

I don't know of any.  Maybe look at examples under .../share/guile/2.2/.

Re: procedure docstrings / documentation

[tantalum]

i don't know of common conventions, but here is what i do:
* i don't repeat the procedure name and parameter names because that can 
be queried at run-time or automatically extracted
* most of the time i write a type signature in the first line of 
docstrings because i find that information useful
* i insert newlines to limit the text width. my editor does not wrap it 
while keeping indent or otherwise formats it
* subsequent lines get one extra space at the beginning to offset the 
initial doublequote of the string literal
* i use a period to mark the end of sentences, but not after the type 
signature or the last word
* in terms of markup i stick to plaintext and indented blocks for 
sections. but texinfo (i think that is it?) is used in guile code as far 
as i know to mark variable names for example, which then get special 
formatting or become part of an index when the documentation is created 
from it

here is an example of a docstring in the way i would write it currently:

(define (test a b)
   "integer string -> integer
    text that describes this procedure,
    multiline as needed"
   (+ a (string-length b)))

i think it is nice to have an example for calling the procedure in the 
docstring.
     "example call: (interleave (list 1 2 3) 4) -> (1 4 2 4 3)"

another thing that i do for documentation in modules is that i export a 
binding with a predictable name, for example if the module is (my 
module-x) i export my-module-x-description and define it like this:

(define my-module-x-description "this module helps with x.
   syntax
     quote-odd :: any ... -> list
       quotes each second argument starting from the first and creates a 
list.
       example: (quote-odd a b c d) -> (list (quote a) b (quote c) d)
   data structures
     file-info: ((integer:mtime . string:path) ...)")

because i don't know how to add docstrings to syntax definitions, i 
document exported syntax in this way.


> Is there any convention on content/formatting for a procedure
> docstring? E.g., should I repeat the procedure name and arguments?
> Should I insert newlines to maintain a certain text width?

> I'm not really clear on how document is done in Guile, overall. I see
> Gieser has ways to look up documention for some procedures/modules, but
> it doesn't seem to pull that information from the docstring, at least
> not my docstrings.

Re: procedure docstrings / documentation

[Arne Babenhauserheide]

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

Christopher Howard <christopher.howard@qlfiles.net> writes:

> No thoughts related to this subject?
> On Wed, 2017-09-20 at 16:18 -0800, Christopher Howard wrote:
>> Is there any convention on content/formatting for a procedure
>> docstring? E.g., should I repeat the procedure name and arguments?
>> Should I insert newlines to maintain a certain text width?
>> 
>> I'm not really clear on how document is done in Guile, overall. I see
>> Gieser has ways to look up documention for some procedures/modules,
>> but
>> it doesn't seem to pull that information from the docstring, at least
>> not my docstrings.

I know what I do, but I’m not sure that’s conventional.

- I insert newlines (via M-q) to keep the code short.
- I describe in the first paragraph what the procedure does, in the way
  I want to read when I call (help procedure). I try to stay at one
  line, but if that makes the info too bad, I use a longer paragraph.
- Then I add two newlines and additional information.

Here’s a mostly OK example:


    (define (cholesky! a)
      "Modifies the square matrix a to contain its cholesky decomposition.
    
    sets a to g with a = ggT,
    
    a is represented as list of lists."
      let : : n : length a
        …

(from
<https://bitbucket.org/ArneBab/wisp/src/b94c06e83108c2422bea0da8d6cf711c9cd26ce3/examples/cholesky.w#cholesky.w-54> )


This is another example:


    (define (logiota steps start stepsize)
        "Create numbers evenly spread in log space"
        (let*
            ((logstart (log (+ start 1)))
             (logstep (/ (- (log (+ start (* stepsize (- steps 1)))) logstart) (- steps 1))))
            (map inexact->exact (map round (map exp (iota steps logstart logstep ))))))

(from
<https://bitbucket.org/ArneBab/wisp/src/b94c06e83108c2422bea0da8d6cf711c9cd26ce3/examples/benchmark.w#benchmark.w-112> )

However I think that my docstrings are rathor too short than too long.

I’m still working a way to add doctests (I plan to add them as property,
not to the docstring).

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein
ohne es zu merken

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: procedure docstrings / documentation

[Christopher Howard]

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

On Sun, 2017-09-24 at 00:47 +0000, tantalum wrote:
> * i don't repeat the procedure name and parameter names because that
> can 
> be queried at run-time or automatically extracted
> 

On this particular point: how do you query the parameter names at run-
time? Or do those have to be extracted from the source?

-- 
https://qlfiles.net
https://emailselfdefense.fsf.org/en/

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: procedure docstrings / documentation

[tantalum]

it is available in procedure properties
https://www.gnu.org/software/guile/manual/html_node/Procedure-Properties.html
i just noticed again that the procedure to get the arguments is 
undocumented.

     Scheme Procedure: procedure-arguments proc
     Scheme Procedure: procedure-documentation proc

there is another way with (system vm program) and 
program-arguments-alist, which also works with procedures
https://www.gnu.org/software/guile/manual/html_node/Compiled-Procedures.html

it can also be useful to get the exports of a module
https://www.gnu.org/software/guile/manual/html_node/Module-System-Reflection.html

    Scheme Procedure: resolve-interface name [#:select=#f] [#:hide='()] 
[#:prefix=#f] [#:renamer=#f] [#:version=#f]

there are more module related procedures that can be found on the repl 
if readline is enabled by typing module- and pressing tab.

it is also possible to extract macro parameters from exported syntax 
transformer procedures.

On 2017-09-25 14:01, Christopher Howard wrote:
> On Sun, 2017-09-24 at 00:47 +0000, tantalum wrote:
>> * i don't repeat the procedure name and parameter names because that
>> can 
>> be queried at run-time or automatically extracted
>> 
> 
> On this particular point: how do you query the parameter names at run-
> time? Or do those have to be extracted from the source?