188.8.131.52 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
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
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.