Quick Reference

1.3.2.3 DOCUMENT comments

Immediately after (within a few lines of) a func, extern, or local statement (see section 1.2.5 Variable scope), you may put a comment which begins with the eleven characters /* DOCUMENT. Although Yorick itself doesn't pay any more attention to a DOCUMENT comment than to any other comment, there is a function called help which does. What Yorick does do when it sees a func, extern, or local (outside of any function body), is to record the include file name and line number where that function or variable(s) are defined.

Later, when you ask for help on some topic, the help function asks Yorick whether it knows the file and line number where that topic (a function or variable) was defined. If so, it opens the file, goes to the line number, and scans forward a few lines looking for a DOCUMENT comment. If it finds one, it prints the entire comment.

The file damped.i has three DOCUMENT comments: one for a fictitious variable called damped, so that someone who saw the file but didn't know the names of the functions inside could find out, and one each for the damped_wave and q_out functions.

Near the end of most DOCUMENT comments, you will find a SEE ALSO: field which feeds the reader the names of related functions or variables which also have DOCUMENT comments. If you use these wisely, you can lead someone (often an older self) to all of the documentation she needs to be able to use your package.

This low-tech form of online documentation is surprisingly effective: easy to create, maintain, and use. As an automated step toward a more formal document, the mkdoc function (in the Yorick library include file `mkdoc.i') collects all of the DOCUMENT comments in one or more include files, alphabetizes them, adds a table of contents, and writes them into a file suitable for printing.