Scheme file docstring format

[Neil Jerram]

>>>>> "Dirk" == Dirk Herrmann <address@hidden> writes:

    Dirk> On 10 Feb 2001, Neil Jerram wrote:
    >> 2. Currently the only snarfed docstrings come from the C code
    >> for libguile.  Documentation for Scheme-defined procedures is
    >> extracted from the lambda body, where the first expression of
    >> the lambda body is a string.
    >> 
    >> I think we should also support snarfing docstrings from Scheme
    >> module files.  Instead of: [...]  we would use a format like:
    >> 
    >> ;;; Removes bindings in @var{module} which are inherited from
    >> the ;;; (guile) module.  (define (purify-module! module) ...)

    Dirk> That's a good suggestion.  The memory overhead for the
    Dirk> documentation strings has always bothered me.  (Well,
    Dirk> mentally :-) I never ran into memory problems because of
    Dirk> docstrings, but I'd like guile to have as small a memory
    Dirk> footprint as possible.)

OK, I'd like to propose a format for Scheme file docstrings, and also
the rule for how the snarfer finds these docstrings.

First the format:

- Following the elisp coding standards, Scheme file docstrings begin
  with two semicolons, aligned with the following `(define ...)'.

- The docstring breaks down into: [PROTOTYPE] DOCTEXT [META-INFO],
  where

  - The optional PROTOTYPE consists of a line whose first word is the
    same as the name being documented.  For example:

;; condition-case THUNK HANDLERS...

    If not specified explicitly, the PROTOTYPE is deduced, if
    possible, from the following `(define ...)' expression.

  - The DOCTEXT consists of an arbitrary number of comment lines that
    have whitespace directly after the two semicolons.  Leading and
    trailing blank lines will be stripped.

  - The optional META-INFO consists of an arbitrary number of comment
    lines that have a hyphen `-' directly after the two semicolons,
    followed by a keyword that indicates the type of meta-information
    provided.

    Details on types of meta-info supported, and how the snarfer
    handles them, can be fleshed out later.  This format definition
    simply provides a mechanism for meta-info to be distinguished from
    the DOCTEXT.

Next the rules:

- Scheme docstring snarfing only applies to top level definitions.

- The snarfer identifies items that may have docstrings by looking for
  `(define ...)' expressions beginning in column 0.

- Having found an appropriate define expression, the snarfer searches
  backwards until it finds a line that does not begin with exactly two
  semicolons.  The region that it traverses in doing this is the
  docstring.

- If the first word of the first line of the docstring matches the
  name being documented, it is taken as the PROTOTYPE line and not
  included in the DOCTEXT.  Otherwise the first line is included in
  the DOCTEXT, and a prototype line is constructed from the define
  expression.

Simple example:

;; Returns a list of file names in directory DIR.  The ordering is
;; reversed with respect to the ordering produced naturally by
;; readdir.
(define (reverse-directory-listing dir-name)
  ...)

Here PROTOTYPE is constructed automatically, and there is no meta
information.

Complex example:

;; reverse-directory-listing DIR
;;
;; Returns a list of file names in directory DIR.  The ordering is
;; reversed with respect to the ordering produced naturally by
;; readdir.
;;
;;-Author: Neil Jerram
;;-Updated: 21st May 2000

(define (reverse-directory-listing dir-name)


What do you think?

        Neil