[Top][All Lists]
[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
- Re: Scheme file docstring format, (continued)
Re: Scheme file docstring format, Martin Grabmueller, 2001/02/17
Re: Scheme file docstring format, Marius Vollmer, 2001/02/18
Re: Scheme file docstring format, Keisuke Nishida, 2001/02/22
Re: Scheme file docstring format, thi, 2001/02/18
- Re: Scheme file docstring format, Michael Livshin, 2001/02/18
- Re: Scheme file docstring format, Neil Jerram, 2001/02/18
- Re: Scheme file docstring format, Michael Livshin, 2001/02/19
- Re: Scheme file docstring format, Neil Jerram, 2001/02/19
- Re: Scheme file docstring format, Carl R. Witty, 2001/02/20