Documenting Modula-3 Interfaces

The advantages of literate programming (embedding documentation in the source code) are that the documentation is available both in the source code and in the online or printed documents, and that chances are greater that updates to the source code and the documentation are synchronized.

Some structuring conventions are required to embed all the documentation information within the comments of the source code. They are relatively simple and are detailed below.

All lines up to and including the first blank line are put into an HTML comment. This makes it easy to omit the source file copyright notice from the documentation. The first blank line must not be within a comment.

The portions of the file that are not in comments will be placed within preformatted (<PRE>) sections, obeying line breaks and indentation. Any characters that have special significance to HTML will be quoted.

The portions of the file that are in comments will be treated differently depending on the position of the comment. There are three cases:

  1. Comments that do not begin in the first column are processed just like program text, and placed in a preformatted (<PRE>) section. In the following example, OUT will be processed like the rest of the line:
    
    PROCEDURE P(VAR (*OUT*) x: INTEGER);
    
  2. Comments that begin in the first column and are not preceded by a blank line are indented and typeset in slanted roman text, except that double-quoted expressions are typeset in slanted typewriter font. The purpose of this is to allow a brief comment after a procedure declaration, indicating what the procedure does. For example, here is the specification of Path.LineTo:
    
        PROCEDURE LineTo(path: T; READONLY p: Point.T);
        (* Extend "path" with a linear segment that starts
           at its current point and ends at "p". *)
    

    It is recommended that these slanted comments be kept brief; additional details can be provided in longer type 3 comments.

  3. Comments that begin in the first column and are preceeded by a blank line are typeset in a roman font and justified. Items enclosed in double-quotes are set in unslanted typewriter font; for example, program identifiers should be double-quoted this way. Line breaks and indentation have no effect in these comments.

    Sometimes you want a portion of a comment to be treated verbatim, like program text, for example, when including an example program. Therefore, any line that starts with "| " (vertical bar followed by space) is treated like program text, typesetting it verbatim in typewriter font.

Comments of type 2 and 3 may contain HTML tags, for example to annotate section headings or emphasize text. A title and level 1 header are supplied using the interface name.

Lines in type-three comments that begin with "| " are treated just like program text with one exception: you can slip in words in roman font by enclosing them in back-quotes.

 
|   ELSIF s `was generated by` LineTo THEN