Generated: September 4, 2002, 15:49:56Copyright ©2002, Kurt NørmarkThe local LAML software home page

Reference Manual of the Schemedoc tool

Kurt Nørmark ©    normark@cs.auc.dk    Department of Computer Science    Aalborg University    Denmark    

Source file: tools/schemedoc/schemedoc.scm
LAML Version 18.00 (August 31, 2002) full

This is the schemedoc tool which takes Lisp style comments and turns them into documentation together with selected program fragments. A number of internal tags in the comments make it possible to express a variety of interface properties in a structured way. The documentation is presented by means of the LAML manual style. The main function (the tool) is extract-documentation-from-scheme-file. Two additional functions used for internal purposes are also documented.

This tool requires the general library, which is NOT loaded by the tool.

If you read this via the documentation and manual facility, this text is extracted from the Scheme source file, which implements Schemedoc. As such, Schemedoc has simply been used on itself.

Table of Contents:
1. How to use comments for documentation purposes.3. The second internal function.5. Known problems.
2. The first internal function.4. Internal tagging support in schemedoc comments.

Alphabetic index:
allowed-duplicates-elementsallowed-duplicates-elementsA list of element names (symbol) for which we allow multiple occurences.
delete-comment-file?delete-comment-file?A boolean variable which tells whether to delete the temporary (by this tool) generated source file, in which comments are syntactical Lisp forms.
extract-documentation-from-scheme-file(extract-documentation-from-scheme-file scheme-file)This function is the main function.
extract-internal-tagging(extract-internal-tagging comment-string)Parse the comment string, in order to extract internal tagging.
extract-relevant-documentation(extract-relevant-documentation file-name)Extract a manual style list of documentation from file-name and return it.
extracted-manual-abstractextracted-manual-abstractA variable holding the extracted manual abstract.
lexical-to-syntactical-comments!(lexical-to-syntactical-comments! scheme-input-file scheme-output-file)Given the source file, scheme-input-file, make another file scheme-output-file, in which the lexical comments are turned into syntactic comments in terms of comment forms.
temp-output-filetemp-output-fileThe name of the file where the function lexical-to-syntactical-comments! places it's output

extract-documentation-from-scheme-file


Form
(extract-documentation-from-scheme-file scheme-file)

Description
This function is the main function. As such, this function IS the schemedoc tool. The function takes as input a name of a scheme file (full path, file extension inclusive). The function returns a list structures suitable for the manual style to display via the function make-manual. Notice that make-manual is not called from this function.


delete-comment-file?


Form
delete-comment-file?

Description
A boolean variable which tells whether to delete the temporary (by this tool) generated source file, in which comments are syntactical Lisp forms. The name of the source file is determined by the variable temp-output-file. By default, the value is t.


 

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:

  1. Each tag starts with a dot '.' and runs through the line, until CR.
  2. The only characters allowed between the semicolons and .key are blank space characters (space, tab).
  3. Internal tags must be at the end of a comment; no descriptions (besides other internal tags) must be found after them.
  4. 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.
  5. The descriptions in .title, .precondition, .example, .comment, .return and .misc is arbitrary free text (without newlines).
  6. There cannot be an internal tag on the first comment line. In other words, the first line must be a description.
  7. 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!


Form
(lexical-to-syntactical-comments! scheme-input-file scheme-output-file)

Description
Given the source file, scheme-input-file, make another file scheme-output-file, in which the lexical comments are turned into syntactic comments in terms of comment forms. The first parameter of a comment form is the number of semicolons in the lexical comment. The second parameter is the comment text itself. Several consequtive lines of (equally leveled comments) are organized in one comment form.


temp-output-file


Form
temp-output-file

Description
The name of the file where the function lexical-to-syntactical-comments! places it's output


 

3.   THE SECOND INTERNAL FUNCTION.
The function in this section extracts relevant level n, n > 2, comments for documentation purposes


extracted-manual-abstract


Form
extracted-manual-abstract

Description
A variable holding the extracted manual abstract.


extract-relevant-documentation


Form
(extract-relevant-documentation file-name)

Description
Extract a manual style list of documentation from file-name and return it. It is assumed that file-name contains syntactical (comment ...) comments.


 

4.   INTERNAL TAGGING SUPPORT IN SCHEMEDOC COMMENTS.


extract-internal-tagging


Form
(extract-internal-tagging comment-string)

Description
Parse the comment string, in order to extract internal tagging. If no internal tagging is found return ((description "comment-string")). If at least one internal tag is found return an a-list of the form ((tag-1-symbol va1-1-string) (tag-2-symbol va1-2-string) ...). The string part before the first tag is returned as (description "string part before first tag") in the list.


allowed-duplicates-elements


Form
allowed-duplicates-elements

Description
A list of element names (symbol) for which we allow multiple occurences.


 

5.   KNOWN PROBLEMS.

A single semicolon comment ; without any trailing text causes problems for the transformation to syntactical comments.


Generated: September 4, 2002, 15:49:56
This documentation has been extracted automatically from a Scheme source file by means of the
Schemedoc tool