Version 13 of Ruff!

Runtime Utility Formatting Function

(acronym expansion subject to change)

Ruff! is the documentation system included with Woof!. Unlike other source documentation systems, Ruff! generates documentation using runtime introspection. This has several benefits:

Less clutter in the source - no extraneous markup like FUNCTION: or @class as hints for the document generator
Less duplication and hence less errors - for example, namespaces, defaults etc. are automatically and correctly picked up.
Documentation can be picked from comments placed next to the corresponding program logic making the code easier to read as well making it easier to keep documentation in sync.
The benefits are even more enhanced when documenting classes as documentation can automatically include inherited classes, mixins etc.
Even program elements with no comments can be documented to provide useful information (eg. default values, parameter sequence, contained methods etc.), particularly if names are well chosen.

Because Ruff! is primarily an input processor, it generates output in canonical format that can be passed to output generators like doctools via adapters. Currently only a doctools adapter is implemented which can be used to generate all the doctools output formats like text, html, tmml, latex etc. A native XML/XHTML adapter is also planned.

Below is some sample source code that illustrates some of these points:

namespace eval ::ruff::test {
    proc print_array {name_of_array {key_pattern *}} {
        upvar $name_of_array arr
        foreach {key val} [array get arr] {
            puts $key:$val
        }
        # Note this proc has no ruff comments
    }

    proc sample_proc {param {param_with_default default_value}} {
        # A sample proc to illustrate ruff! This is the summary line
        # (or lines). It may or may not have a whitespace line following it.
        #  param - a parameter to the procedure.
        #  param_with_default - another parameter but with default value. Note
        #    the parameter description may cover multiple logical and
        #    physical lines.
        #
        # This is a general description paragraph. Paragraphs are separated
        # by lines that only have the comment character # and  whitespace
        # 
        # Introspective documentation generation allows correct pickup
        # of namespaces in procedure names, less duplication, minimal
        # extraneous symbols.
        #
        # Returns the empty string.

        set foo bar

        return ""
    }
}

...and the corresponding documentation generated via ruff as plain text output (via doctools). Of course, anything supported by doctools can be generated similarly (tmml, html etc.)

test - 
Generated from file 'woof.man' by tcllib/doctools with format 'text'
test(1) 0.1 woof ""

NAME
====

test -

SYNOPSIS
========

::ruff::test::sample_proc param param_with_default
::ruff::test::print_array key_pattern name_of_array

DESCRIPTION
===========

    ::ruff::test::sample_proc param param_with_default

        param

            a parameter to the procedure.

        param_with_default

            another parameter but with default value. Note the parameter
            description may cover multiple logical and physical lines. (default
            *default_value*)

        A sample proc to illustrate ruff! This is the summary line (or lines).
        It may or may not have a whitespace line following it.

        This is a general description paragraph. Paragraphs are separated by
        lines that only have the comment character # and whitespace

        Introspective documentation generation allows correct pickup of
        namespaces in procedure names, less duplication, minimal extraneous
        symbols.

        Returns the empty string.

    ::ruff::test::print_array key_pattern name_of_array

        key_pattern

            (default ***)

        name_of_array

COPYRIGHT
=========

Copyright (c) 2009 "Ashok"

AMG: Looks very exciting! I can't wait to see the code for this. I'll be happy to start using it in my projects.

Many years ago I had thought of writing a documentation generator, but it had not occurred to me that I could harness Tcl's vast introspection capabilities. As a result, it would have been extremely limited, doing nothing more than extracting specially-formatted comments (while ignoring the actual code) and dumping them to HTML or similar. It would have allowed me to interleave code and documentation, but it would also have required that the documentation effectively duplicate the code.

Side note: On this Wiki, be careful with words underlined with ==='s, when the words are three or six characters long. The underlines may be interpreted to start or stop a block of preformatted text!

RUntime Fact Finder?

Category Documentation