[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Scheme file docstring format
From: |
Neil Jerram |
Subject: |
Scheme file docstring format |
Date: |
16 Feb 2001 18:45:37 +0000 |
>>>>> "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
- Scheme file docstring format,
Neil Jerram <=