Version 10 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.

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"

Category Documentation