TclDoc - The Tcl API Document Generator
Following in a series of standalone Tcl development tools (fickle, taccle) comes yet another Tcl API generator. Well, maybe not the "yet another" part because at the time I started writing this (summer of 2001) there were no others I knew of. I see that since then others have written autodoc and zdoc. TclDoc differs in that it has tcldoc tags as well as keeps track of procedure calls.
In a nutshell TclDoc scans one or more Tcl source code files and generates HTML pages representing the logical structure of the code. It looks for special tcldoc tags within comment blocks to lend this structure. An example tcldoc comment block is:
# Glob recursively across a directory and its subdirectory for all
# files matching a list of extensions. Return all matches as a flat
# list.
#
# @param dir root directory to scan
# @param exts list of extension (e.g., <code>*.tcl</code>) to search
# @return list of matching files
proc glob_all {dir exts} {
#...
}Compare this comment with the generated HTML: http://tcl.jtang.org/tcldoc/tcldoc/tcldoc.tcl-annot.html#glob_all . Those who have used javadoc[L1 ] to document their Java code will quickly find TclDoc's syntax comforting. (Okay, I confess -- I used the exact same syntax that javadoc employs.)
Enough jibber-jabber; an example use of TclDoc is at http://tcl.jtang.org/tcldoc/bwidget1.6-demo/index.html . I took a stock BWidget 1.6 distribution and ran TclDoc against it. Go ahead and browse through the files.
TclDoc can handle nearly all types of valid Tcl code; it does choke on dynamically generated procedures because TclDoc only performs static analysis. If you have a specific bit of Tcl code that TclDoc cannot handle please post it below.
TclDoc is a work in progress. At this time import and export do not work, so ignore the section in the manual describing them. You can get the current tcldoc here: http://tcl.jtang.org/tcldoc/tcldoc.tar.gz . Be aware that I am still working on it. The manual page is here: http://tcl.jtang.org/tcldoc/tcldoc.html .
And what good would TclDoc be if it couldn't scan itself? Take a look at the results of running on itself: http://tcl.jtang.org/tcldoc/tcldoc/index.html .
Return to Jason Tang
Category Application | Category Dev. Tools | Category Documentation