1. HOW TO USE COMMENTS FOR DOCUMENTATION PURPOSES.
In order to have documentation extracted, the documentation is organized in comments
with one, two, three, or four initial semicolons. Recall that semicolons are the Lisp lexical
comment symbols: The rest of a line with a semicolon is a comment.
All one comment semicolon comments are ignored by this facility. N semicolon comments, N higher than one, are called SchemeDoc comments.
Two semicolon comments are used as comments of define forms. You can either place
the comment before the define form or after the name/signature of the define form.
Three semicolon comments
are used for text sections between documented forms. The first
sentence (separated with '.' and a space) is used as the title of the text section.
(This text your are reading now - in a browser- is written in a three semicolon comment).
Four semicolon comments are used as the introduction to a documentation document.
There should, as such, only by one four semicolon comment in a Scheme file.
Please notice that function definitions of the form
(define f (lambda (par) ...))
should be documented with a two semicolon comment before the form, whereas
(define (f par) ...)
can be documented with two semicolon comments before the form or just after (f par).
If you have two semicolon comments both before and within the define form they are concatenated.
It is possible to use HTML formatting within a schemedoc comment.
In comments at level two there
may be additional internal tagging at the end of the comment. Here is an example:
;; Return the fifth element of a list
;; .form (fifth x)
;; .parameter x must be a list
(define fifth (make-selector-function 5))
The Schemedoc tool parses the comments and returns a list like
(
(description "Return the fifth element of a list")
(form "(fifth x)"
(param "x must be a list")
)
The manual producing tool may decide to parse additional parts of the strings (the cadr parts of the lists shown above).
The general format of an internal Schemdoc tag is:
.key description.
The rules concerning internal tags in Schemedoc comments are the following:
- Each tag starts with a dot '.' and runs through the line, until CR.
- The only characters allowed between the semicolons and .key are blank space characters (space, tab).
- Internal tags must be at the end of a comment; no descriptions (besides other internal tags) must be found after them.
- key can be an arbitry symbol without spaces. The manual style, however, only recognizes title, form, pre-condition,
description, parameter, reference, internal-references, misc, and comment.
- The descriptions in .title, .precondition, .example, .comment, .return and .misc is arbitrary free text (without newlines).
- There cannot be an internal tag on the first comment line. In other words, the first line must be a description.
- Of parsing purposes, string quotes must be used around categories, anchors, refs and urls in .reference and .internal-references.
The following internal tags are supported
.title Some title
.form (form-name par1 par2)
.pre-condition Some Precondition
.description Some Description
.parameter par-name parameter description
.example some example
.reference "category" "anchor" "url"
.internal-references "category" "ref1" "ref2" ...
.misc Miscelaneous information
.comment Internal comment
.returns Return value description
Internal references support categorized cross references within the current manual page.
A reference is a categoried reference from an anchor to an arbitrary url.
We see that all manual clauses of the LAML manual document styles are supported except
parameters (plural) and cross-references. These two are made
automatically from a number of parameter clauses (singular), and a
number of reference and internal-references clauses (not necessarily adjecent).
2. THE FIRST INTERNAL FUNCTION.
The function in this section makes lexical Lisp style comments to syntactical comments.
We document it because it may be useful in its own right.
lexical-to-syntactical-comments!