This document demonstrates how Spheres should be documented, using a LAML SchemeDoc subset.
These are the rules of the format:
- A comment block is a consecutive sequence of comment lines, which are not separated by empty, blank or non-comment lines.
- The number of semicolons may vary from one comment line to another within a comment block.
- The number of semicolons used for a documentation comment is not significant.
- The documentation comment character is a distinguished character: '!'.
- A documentation comment is a comment block which is identified by one or more documentation comment characters on the first line of a comment block.
- The documentation comment characters must appear after the semicolon(s), only separated by spaces or tabs. The comment extraction facility 'eats' and eliminates a possible single white space following the '!' or ';'.
- The documentation comment character is only recognized in the first line of a comment block (and next to a semicolon). Documentation comment characters located other places within a comment count as normal characters.
These are the types (hierarchy) of documentation comments:
- Comments marked with a single documentation comment character (!) 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.
- Comments marked with two documentation comment characters (!!) are used for text sections between documented forms. The first sentence (separated with '.' and a space) is taken as the title of the section.
- Comments marked with three documentation comment character (!!!) are used as the introduction to a documentation document. There should, as such, only be one documentation abstraction comment in a Scheme file. The documentation abstraction comment should be the first part of Scheme source file.
Python 2.5 is no longer available. Please refer to https://goo.gl/aESk5L for more information