# 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[1] 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.
- tcldoc 0.83 (Oct. 06-2011) at http://heinlein-public.s3-website-eu-west-1.amazonaws.com/
- 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
- import / export abilities
- hyperlink to the top of comment blocks instead of the procedure declaration
- perform run-time analysis so as to resolve namespace eval
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 listjt 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 REQUESTSRLH 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 SourceDirIt 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-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-October-04: -> This seems to be easy. Let's see.
[ttt] 2011-October-10: -> see V0.83 beside some bug fixes .... a new Command Line Option '--synonym' that should solve your 'method'-Problem
Return to Jason Tang