docc is an automatic documentation-maker perl script which is invoked like this, for example, from the doc subdirectory of a package, assuming the sources are in the src subdirectory:
docc ../src/*.cIt produces an html file for each routine and a file "buttons.html", which consists of a button and file reference for each routine's html file. A sample-file, extracted from some working code, which works well with docc may be viewed by clicking here. Running docc on that produces this buttons file. The style in this sample is by no means obligatory, but it contains the essential elements of comment-documented code which docc looks for. Note particularly that the line contained on the "Description" line, for each procedure, is included in the buttons file as a brief, one-line description.
Routines are recognized by this sequence: <type> <name> ( <list> ) { <code> } with comments permitted anywhere. The comments, up until the "{" or first code following a "disarming keyword", are included in the document.
These occur in a comment; searches are case-insensitive.
DESCRIPTION: -- 1st or 2nd word in line -- remaining text on line goes into buttons file. RETURNS: -- 1st or 2nd word in line CONDITIONS: -- 1st or 2nd word in line PURPOSE: -- 1st or 2nd word in line AUTHOR: -- 1st or 2nd word in line VALUE: -- 1st or 2nd word in line FUNCTIONAL -- 1st word in line only BRIEF: -- 1st word in line -- remaining text on line goes into buttons file.This list is based on brief experience with what works, and will likely expand as needed. Mispellings are not recognized.
docc attempts to be flexible in recognizing documentation headers at the beginnings of C procedures. It recognizes C procedure definitions as described above; any others will not work, and the author (no C-expert!) should be informed as to the oversight. It is flexible as regards spacing, provided words themselves aren't broken up (eg, DESCRIP TION wouldn't work as a disarming keyword). All searches are case-insensitive with optional spacing between words in multi-word searches.
Once it sees the start of a procedure, it starts looking for a disarming keyword, and just copies the lines from the procedure into the html file until it decides the document is done. It makes that decision by first "disarming" on any of several disarming keywords, occuring as the first or second word on a line in a comment. Those that require a colon permit optional spaces between the word and the colon. Once disarmed, the first non-comment line terminates the document, and it starts looking for the next procedure (blank lines and form feeds are comments).
docc permits actual type-declaration statements to become part of the document, provided they occur in the procedure's argument list.
If it encounters an EOF, it spits out a warning message, then ends the current document and continues.
The html files consist of a highlighted procedure-declaration, with all its arguments, and continued if that's how it's written in the *.c file. The rest of the document is just encapsulated in an "as-is" block, and appears as in the source.
In addition to these html files, docc also produces a "buttons" file, named buttons.html, consisting of a line for each procedure found which refers to the corresponding html file for that procedure. The button is named after the procedure itself, stripped clean and case-preserved (the *.html filenames are all case-identical to the actual defined procedures), and is appended with a one-line description if the procedure was written with a line containing:
Brief description: This procedure does something.or:
Description: This procedure does something, too.The "brief description:" or "Description:" is required, with no alternatives at the moment. The "Brief Desription:" or "Description:" portion is stripped off and not put in the buttons file. docc also prints a line on the terminal for each procedure found, as well as error messages when docc determines that it's confused.
The buttons.html file should get renamed or incorporated somewhere else, with perhaps a minimal of editting, such as to eliminate reference to some procedure, if desired. Several buttons.html files, corresponding to multiple procedure-documentation lists, may be generated, with each buttons.html file renamed or included before the next step is started.
Generally, when docc makes an error it's because a disarming keyword is absent, and it does well there, too, in only incorporating that one (first) line of code before it figures out that it's not in the header anymore. And, of course, it prints warnings for these cases.
Once the various *.html files are produced, and the buttons.html file renamed or incorporated, the documentor has only to put things in the right place for WWW.