IntroductionMain

Ruff! (Runtime function formatter) is a documentation generation system for programs written in the Tcl programming language. Ruff! uses runtime introspection in conjunction with comment analysis to generate reference manuals for Tcl programs.

Ruff! is covered by a liberal BSD open-source license that permits use for any purpose.

Why Ruff!Main

In comparison with other source code based documentation generators, Ruff! produces documentation that not only requires less duplication of effort from the programmer, but is also more complete, more accurate and more maintainable.

  • Comments in source code do not have to be reproduced for documentation purposes.
  • Ruff! requires minimal markup in the comments making it lightweight as well as reducing clutter.
  • Supports inline formatting using Markdown syntax.
  • Program elements like command arguments, defaults and class relationships like inheritance are automatically derived.
  • Maintenance is less of a burden as documentation is automatically updated with source modification such as changes to defaults, addition of mix-ins etc.

On the output side,

  • Ruff! supports multiple formats (currently HTML and Markdown). Additional formats can be added through subclassing.
  • Generated documentation can optionally be split across multiple pages.
  • Hyperlinks between program elements, and optionally source code, make navigation easy and efficient.
  • In object oriented code, class relationships are extracted and the full API for a class, with inherited and mixed-in methods, is flattened and summarized.

The Ruff! documentation itself is produced with Ruff!. For a larger example, see the CAWT reference manual or the reference pages for Woof! (though the latter is with an older version of Ruff!).

DocumentationMain

The ::ruff reference page describes the Ruff! documentation generation API. The ::ruff::sample page shows some sample output for some of the Ruff! features along with the associated source code from which it was generated.

Downloads and InstallMain

Download the Ruff! distribution from https://sourceforge.net/projects/magicsplat/files/ruff/. The source code repository is at https://github.com/apnadkarni/ruff.

To install, extract the distribution to a directory listed in your Tcl auto_path variable.

CreditsMain

Ruff! is authored by Ashok P. Nadkarni.

It uses the textutil package from tcllib and a modified version of the Markdown inline parser from the Caius project.

Document generated by Ruff!
© 2019 Ashok P. Nadkarni