Re: Scheme file docstring format

[Marius Vollmer]

Neil Jerram <address@hidden> writes:

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

I like your suggestion.  But Id also like to see a discussion of why
this is better than the existing way of doing things, with a real
string.  (I think your suggestion _is_ better, but I like to know what
other people think.)

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

I think it would be good to allow meta-lines to be interspersed
arbitrarily with doc-lines.