Yorick: DOCUMENT

Home Manual Packages Global Index Keywords 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.