docscm is a collection of simple tools for extracting function-, variable-, and record-documentation from Scheme source files, and generating DocBook XML output suitable for further processing. It is written using the Chicken[1] scheme system, and draws inspiration from Javadoc, Doxygen, and Aubrey Jaffer's schmooz[2]. While it lends itself particularly to generating API documentation, it can also be used to help automate parts of the normal DocBook processing chain.
Scheme files containing specially-formatted comments are read by extract-doc, which outputs a loose form of SXML[3]. This output is then converted to XML by sxml2xml. Finally, the XML output fragments can be included in DocBook documents using standard SGML entity inclusion. Some rules for GNU make are included which automate parts of the documentation compilation process.
;;@ ;; Returns <varname>arg</varname> multiplied by two. (define (double arg) (* arg 2))docscm comments start on a line of their own, with any amount of leading whitespace, n leading semicolons, and an at-sign. They continue until the next line which starts with a different number of semicolons. docscm comments are associated with the S-expression immediately following them - in the example above, the comment is associated with the definition of double.
If the at-sign in the comment leader is followed by whitespace or newline, then the comment is associated with the following definition (if any). However, if the at-sign is immediately followed by an identifier, the rest of the line is parsed as a list of parameter S-expressions to the command named by the leading identifier.
[1] | |
[2] | |
[3] |