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.
TclDoc Tags
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.)
So what makes TclDoc different than the other documentation generators?
TclDoc has the following features:
Examples
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 an older version of TclDoc against it. Go ahead and browse through the files.
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 .
Downloads:
TclDoc is a work in progress. At this time import and export do not work, so ignore the section in the manual describing them.
Download tcldoc from below:
The current manual page is here: http://heinlein-public.s3-website-eu-west-1.amazonaws.com/tcldoc.html .
To Do
TclDoc can handle nearly all types of valid Tcl code; it can fail on some 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 or email it to me [L2 ].
Things that I want to fix / add:
jt 05 Oct 2004 - Looks like I made a slight mistake when displaying a procedure's @deprecated tag. On line 529 of tcldoc_scanner.tcl change the [string time ...] to [string trim ...]. I'll fix this in the next release Real Soon Now.
jt 29 Oct 2004 - the current download fixes this as well as a few other things; see the ChangeLog for complete list
jt 05 Nov 2004 - a bunch of bug reports; suggestions merged into the first official TclDoc release. I figured this is around the third or so time I've updated the publicly available package, so this version is henceforth number 0.3.
FEATURE REQUESTS
RLH 2006-Apr-04: I was looking at the Javadoc tags and Java has @throws for annotating exceptions. It would be nice to have @catch for tcldoc to do the same thing for Tcl.
# @catch This catches whether the input file is...blah.
RLH 2006-Apr-04: This isn't a Javadoc one but it would be nice to have @created to add to the header to show when the file was created initially.
# @created 2006 April 04
PW How am I supposed to use this? run it? source it? It just throws an error. Why not just make it a package?
RLH Did you read the docs? I didn't have any problems at all running it. Basically you do something like:
tclsh path/to/tcldoc.tcl docs filename.tcl
PW Thanks, that works well. I did read the doc, but I admit I did not have much time to play around with it. I think it would be more elegant though to do:
package require tcldoc tcldoc DocDir SourceDir
It works well though. The only thing that causes a big problem for me is it doesn't recognize folder heirarchy. If you have a large app with lots of folders and subfolders, it appears you need to document each folder seperately. Even if you doc them all at once, files with the same name but in seperate folders will skew the documentation.
RLH Yeah, maybe a recursive switch for tcldoc to search in subdirs?
MHN 2010-Jul-21: Trying to enhance a tcl project with tcldoc comments / templates, I have not found any tool to generate it :-( My first attempt with fickle has become an unlucky mixture concerning the usage of states and regex... However, it works for many valid versions of proc commands. All comments are welcome! http://www.box.net/shared/phxvrk5daz
MHN 2011-May-12: The index proc entries should link to the annotated documentation. This makes sense for "by name" and "by file". A patch can be found at http://www.box.net/shared/cn3cnso1z3 . All comments are welcome!
RFox 2011-October-03: Might be nice to have a way to define exactly what a 'proc' is. Here I'm thinking about twisting the code around to generate documentation for some code written in various OO packages.
ttt 2011-October-04: -> RFox: would be nice to have some examples
RFox 2011-October-14:
Consider a program written using snit, I'd like to at least have the0 method command treated like a proc for the purposes of documentation generation. This is assuming there's not likely to be any generic understanding of OO in tcldoc in the near future (e.g. being able to treat a class or snit::type or snit::widget as a coherent entity that looks to the world like a command ensemble).
package require snit
...
snit::type {
...
# Method to do something on the object.
# @param this is a parameter.
# @return here is what is returned
method someMethod {param} {
...
}
}Return to Jason Tang