draft

some available options and examples

(define (test a b)
  "this is a docstring"
  code ...)

• in scheme, the first string in a define/lambda body will be associated as documentation with the procedure.
• note how it is neatly inside the procedure block, with the procedure name as a heading
• describe briefly what a function does, what the parameters control. with documentation in general the "why" is usually important
• docstrings may contain markup. you could use gnu info syntax, markdown or just indentation
• i often see docstrings without indent moved to start at the beginning of the line. this disrupts the nesting with indentation. i find it easy to strip the indent when formatting docstrings for automated documentation generation, so i am not sure why this is done
• idea: a type signature "integer integer string -> (string ...)" in the first line of the docstring

modules have no automatically associated docstrings but it is possible to define a variable with a string.

(define-module (a b))

(export a-b-description "this is a description of the module")

the name can be constructed from the module name and used to lookup module documentation.

a generic way to document syntax is to do so in the module description:

(define-module (a b))

(export a-b-description
  "this is a description of the module
   # syntax
   quote-odd :: a ...
     quotes every second element")

guiles (or guile-libs) define-syntax-rules supports a docstring as a middle argument:

(define-syntax-rule pattern "docstring" expansion)

the sph-script repository contains guile-display-documentation, which you can save and use with guile. sph-lib must also be installed for it to work. add the executable bit with "chmod +x filename" and move the file into a path listed in the environment variable $PATH to have it as a global command line command.

guile-display-documentation "(sph string)"

parameters
  options ... module-name
description
  display documentation (bindings, arguments and docstrings) extracted from guile modules.
  module name is with brackets, for example "(rnrs hashtables)".
  format is either indent, markdown, signature or list. the default is indent
options
  --about | -a
  --format=value | -f value
  --help | -h
  --interface

• resolving the module, (resolve-module name)
• iterate over its bindings (variables, syntax)
• use guiles procedure arity and procedure docstring getters on the objects