13.2.5 Doc Extraction from Scheme Source

For Scheme source files, use doc-snarf. This program supports a variety of output formats, but we are primarily interested in -D to generate GDFv1 output (see guile-tools doc-snarf). A canonical Makefile.am frag example:

     SUFFIXES = .scm .doc
     .scm.doc:
             guile-tools doc-snarf -D -o $@ $<

There are two types of docstrings that doc-snarf recognizes: pre-procedure comments and standard internal. The former are flush-left, begin with two semicolons, and must touch the procedure form that follows it (without any intervening lines of whitespace). The latter are basically strings in the first position of the procedure body. This example demonstrates both types:

     ;; This comment not snarfed; the next form
     ;; isn't a procedure definition.
     (use-modules (ice-9 documentation))
     
     ;; This is a pre-procedure comment docstring.
     ;; It can be multiple lines and have
     ;;    arbitrary
     ;;            internal
     ;;        indentation.
     ;;
     ;; As long as the next line "touches" the proc we are ok.
     ;;
     (define (message-from-the-leader subjects)
       "This is a standard internal docstring.
     It can also be multiple lines and have
        arbitrary
                internal
            indentation.
     Unlike the pre-procedure comment docstring, however,
     we need to escape double quotes \"like this\"."
       (simple-format #t "greetings ~A, did you know:~%~A???~%"
                      subjects (object-documentation
                                message-from-the-leader)))

In the case where there are both types of docstrings, doc-snarf uses the standard internal and ignores the pre-procedure comment.