guile-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Scheme file docstring format


From: Neil Jerram
Subject: Re: Scheme file docstring format
Date: 19 Feb 2001 22:59:33 +0000

>>>>> "Marius" == Marius Vollmer <address@hidden> writes:

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

I think that discussion is now under way.  I just thought of two
simple points that have not been expressed yet, one on each side of
the discussion.

In favour of real strings: using a real string avoids the problem of
needing some kind of heuristic to determine which comment lines form
the docstring for a definition.

In favour of comments: using a real string is messy because it
overloads something - the BODY of a definition - that was otherwise
unambiguous.  How do you explain that in `version' -

(define (version)
  "1.4.1")

- the string is the result of the function call, while in `fraz' -

(define (fraz)
  "arfle barfle gloop"
  ...)

- the string is the docstring?


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

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

Sounds OK to me, although I can't see significant utility from it.

        Neil



reply via email to

[Prev in Thread] Current Thread [Next in Thread]