unofficial mirror of guile-user@gnu.org 
 help / color / mirror / Atom feed
* Re: procedure docstrings / documentation
@ 2017-09-24  0:47 tantalum
  2017-09-25 14:01 ` Christopher Howard
  0 siblings, 1 reply; 7+ messages in thread
From: tantalum @ 2017-09-24  0:47 UTC (permalink / raw)
  To: Guile user

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.



^ permalink raw reply	[flat|nested] 7+ messages in thread
* procedure docstrings / documentation
@ 2017-09-21  0:18 Christopher Howard
  2017-09-23 20:56 ` Christopher Howard
  0 siblings, 1 reply; 7+ messages in thread
From: Christopher Howard @ 2017-09-21  0:18 UTC (permalink / raw)
  To: Guile User Mailing List

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

^ permalink raw reply	[flat|nested] 7+ messages in thread
end of thread, other threads:[~2017-09-26  9:32 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-09-24  0:47 procedure docstrings / documentation tantalum
2017-09-25 14:01 ` Christopher Howard
2017-09-26  9:32   ` tantalum
  -- strict thread matches above, loose matches on Subject: below --
2017-09-21  0:18 Christopher Howard
2017-09-23 20:56 ` Christopher Howard
2017-09-23 23:11   ` Matt Wette
2017-09-24  6:49   ` Arne Babenhauserheide

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