TclDoc is an documentation tool that extracts special formatted comments from source code. It is comparable with javadoc but it differs in that it has tcldoc tags as well as it keeps track of procedure calls.
Since TclDoc combines both
it also helps to document ex post or to do reverse engineering.
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/tcl/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.)
TclDoc has the following features:
An example use of TclDoc is at http://tcl.jtang.org/tcl/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://th-labs.de/tcldoc/tcldoc_docs/index.html .
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://th-labs.de/tcldoc/tcldoc_docs/tcldoc.html .
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 2004-10-05: 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 2004-10-29: the current download fixes this as well as a few other things; see the ChangeLog for complete list
jt 2004-11-05: 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.
RLH 2006-04-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-04-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-04-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-07-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-05-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-10-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-10-04: RFox: would be nice to have some examples
RFox 2011-10-4:
Consider a program written using snit, I'd like to at least have the method command treated as a synonym for the proc command 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} {
...
}
}In its simplest form I'd want to tell tcldoc that method is a synonym for proc.
ttt 2011-10-04: This seems to be easy. Let's see.
ttt 2011-10-10: see V0.83 beside some bug fixes .... a new Command Line Option '--synonym' that should solve your method-Problem
MHN 2012-02-22:
It seems that the address of ttt(?) provided at http://heinlein-public.s3-website-eu-west-1.amazonaws.com/ has a strict filter... is this page the only way to communicate bugs?
Some of the following release 0.83 bugs (some from 0.3) have easy fixes, others might not:
I can provide my full delta to 0.83. Please understand, that I cannot provide per-bug patches! http://www.box.com/s/1hlx8pak6vxrehdk1adt (also see 2013-Feb-04 below (*))
ttt 2012-05-06: Bugs fixed - see version 0.84
MHN 2012-05-07: Thank you! Unfortunately, my motivation to share further changes was gone after a while of no feedback. It's back.
http://www.box.com/s/54a53fe7aceec0914835
The above patch is quite simple. More stuff will follow - I just need to get 0.84 running in our build environment.
ttt 2012-06 17: added the features 'exclude' and 'prune' - but a bit different
MHN 2013-02-04:
(*) My fix for the "last word of the summary" issue was not complete - and maybe even wrong. Use the following regexp near the end of tcldoc_scanner.(fcl|tcl) in proc get_summary:
\A([^\.]*\.?)(\s|\Z)
Note, that this is still buggy when a dot followed by non-whitespace.
nagu 2013-05-31 05:35:20:
Is it possible to add support for source files based on object oriented frameworks like itcl that will generate documentation at class level similar to javadoc? Documentation to include: Class inheritance hierarchy, public & protected member variables and public and protected methods. I tried multiple --synonym options like:
tcldoc --synonym "public method" --synonym "protected method" --synonym "public variable" --synonym "protected variable" doc .
expecting that tcldoc will pickup all these variations. But, it only recognizes the last --synonym option and ignores the previous ones. Also, in the output, it prefixes an unwanted :: to method/variable names with the title "Procedure Summary/Detail".
Hence, I feel --synonym alone cannot meet OO specific requirements. Instead, it will be good to have specific plugins (e.g., itcl-plugin, snit-plugin etc) like Doclets in javadoc added to tcldoc.
APN Nagu, see if Ruff! meets your needs (sample output ). It will output to multiple formats but currently (and probably forevermore) only supports TclOO, not ITcl or Snit (unless someone does the additional work).
MHN 2015-01-22: Find a patch for tcldoc-0.85 at http://app.box.com/s/gkdwr9ur6zgdiw29kgnhj776as57922p (as-is with no warranty):
ttt 2015-05-03: included MHNs patch and build a 0.87
Tcldoc v0.87 got the problem (Unmatched "[" (file code.tcl, line 1)) when scanning the below section code:
foreach keyLen [lsort [array names arrReport]] {
set valueLen $arrReport($keyLen)
set keyLen [string map {_ ][} $keyLen]
set keyLen [string map {[NP] [NMOS] [PP] [PMOS]} $keyLen]
puts $outReport "\[$keyLen\] => $valueLen"
}