Version 23 of Ruff!

Updated 2009-04-17 10:55:13 by APN

RUntime Formatting Function

(acronym expansion subject to change)

APN 2009-04-17 Ruff! 0.2 has been released. The major enhancement in this release is the inclusion of a built-in HTML formatter so no external tools are necessary. The formatter supports automatic linking, navigation, tooltips. See the links below.

Ruff! uses runtime introspection in conjunction with comment analysis to generate reference manuals for Tcl programs. Runtime introspection allows Ruff! to correctly generate cross-reference and links across class and namespace hierarchies.

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

The user guide is at http://woof.magicsplat.com/ruff_guide . The reference pages at http://woof.magicsplat.com/manuals/ruff/index.html provide an example of Ruff! generated documentation.


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?


I think that RS's docstring is noteworthy here, it's a concise demonstration of the mentioned introspection capabilities to document Tcl source. -- Effe APN Hmmm... that's only ten lines. I better go figure what the other 2490 lines of my code are doing! Effe: I don't want to criticize your work! I just wanted to point to the core concept of introspection to gather the needed information, it's a mind-sized bite to understand a tiny part of your program (and a tiny part of Tcl). I learned myself much about Tcl's capabilities by following link after link on this wiki and this is one of those links, tightly coupled to the topic. The honor of giving us a much more elaborated work that goes far beyond docstring is nevertheless due to you. APN Effe I really didn't take your reference as criticism at all! Honest! My remark was purely in jest, not intended as sarcasm. As you say, the Wiki offers a lot, and if you see any of my open source code, you'll see lots attributed to various Wiki pages in the comments.