Basic Document Generation

Ruff! is a package that generates documentation using runtime introspection in conjunction with smart parsing of comments in proc and method bodies.

Runtime introspection is primarily through the Tcl info command. Comments within proc and method bodies are also processed at run time and not by analysing source files. Therefore, only comments inside proc and method bodies are visible to Ruff!.

Ruff! requires almost no markup and uses wiki-like free formatting conventions for structured text like lists.  A simple proc definition with Ruff! markup would look like this:

proc character_at {str {index 0}} {
       # Fetches the character at the specified position in the string
       # str - string from which character is to be retrieved
       # index - position in string from which character is to be retrieved
       if {$index < 0} {
           #ruff
           # If the index has a negative value, it is taken as the position
           # from the end of the string.
           ...some code...

           # The above comment about index gets documented by Ruff! because
           # of the #ruff marker even though it appears in the middle of the
           # program body. This comment does not get picked up by Ruff! because it
           # it appears in the middle of the code and has no #ruff marker attached.
       } else {
           ...some code...
       }
   }

Below is the output generated by the Ruff! using the doctools formatter:

character_at str ?index?

str

string from which character is to be retrieved

index

position in string from which character is to be retrieved (default 0)

Fetches the character at the specified position in the string

If the index has a negative value, it is taken as the position from the end of the string.

Note the markup is not obtrusive. Refer to the documentation of the distill_body and parse commands for the exact syntax. The source code for Ruff! itself is the best example of comment formatting conventions for Ruff!.

Because Ruff! gets its input purely from runtime information, to use it to generate documentation for a set of commands or classes, it must first be loaded into the same interpreter as those commands and classes. Use the package command to do so as below:

package require ruff