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[http://java.sun.com/j2se/javadoc/] 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:
   * Takes original Tcl source file(s) and generates an HTML equivalent page.  The page hyperlinks procedure calls to their declarations (not necessarily within the same file).  It also highlights comments for easier perusal.
   * Using the same file(s) generates an ''annotated'' view that summarizes the contents of the code.  The annotated view extracts comments from the file to create a description of its API.  Users of javadoc will appreciate this feature.
   * Builds indices of all discovered files and procedure declarations.
   * Builds an index of all known ''procedure calls'' hyperlinked to where the call occurrs.  This ability is particularly useful whenever one changes the order of arguments to a procedure and needs to ensure that all calls to that procedure have been updated.
   * Builds an index summarizing all files and procedures.

'''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:
   * '''tcldoc 0.3 at http://tcl.jtang.org/tcldoc/tcldoc-0.3.tar.gz.'''
   * '''original tcldoc at http://tcl.jtang.org/tcldoc/tcldoc.tar.gz'''

The current manual page is here:  '''http://tcl.jtang.org/tcldoc/tcldoc/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 [mailto:tang@jtang.org].

Things that I want to fix / add:
   * import / export abilities
   * hyperlink to the top of comment blocks instead of the procedure declaration
   * discover namespaces and group into hierarchy
   * perform run-time analysis so as to resolve namespace eval
   * use cascading style sheets, so as to be HTML 4.0 compliant.  as an added bonus, this allows me to add mouseovers to procedure declarations that will pop up its declaration

----

[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.

----

Return to [Jason Tang]

----

[Category Application] | [Category Dev. Tools] | [Category Documentation]