tcldoc

Disambiguation edit

latex tclldoc: a Latex package and document class for literate programming with Tcl

TclDoc - The Tcl API Document Generator (v0.87 / May 3 - 2015) edit

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

linking views which summarizes the contents of the code with the source code
and the tracing of procedure calls

it also helps to document ex post or to do reverse engineering.

TclDoc Tags edit

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[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? edit

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 occurs. 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 edit

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

Downloads edit

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.87 (2015-05-03) at http://th-labs.de/tcldoc/TclDocInfoPage.html
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://th-labs.de/tcldoc/tcldoc_docs/tcldoc.html.

To Do edit

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

Things that I want to fix / add:

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

Feature Requests edit

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:

MAJOR+FIX: Crash when no procs are exported (can't read "::EXPORTED_PROCS": no such variable)
MAJOR: Global links are not resolved (warning - cannot resolve "@see http://wiki.tcl.tk/5598 http://wiki.tcl.tk/5598")
MAJOR+FIX: line wrapped {@link} tags are not recognized
MAJOR+FIX: line wrapped proc declarations are not recognized
MAJOR+FIX: The path of the stylesheet is written to the output.
MINOR+FIX: 0.83 says it is 0.81 in the output files
MINOR: "proc ::myglobal ..." produces documentation of "::::myglobal"
MINOR+FIX: The summary of single sentence descriptions misses the last word. (also see 2013-Feb-04 below (*))
MINOR+FIX: Invalid <a> link in output.
MAJOR+FIX: Crash (instead of error message) when line number not yet set.

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.

FEATURE: added command line parameters --suffix, --exclude, and --prune

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):

generate valid SGML and tidy HTML
- anchors use the id attribute (instead of name)
- anchor id must not contain special characters
- tables require a summary
- multiple dashes in a comment are discouraged
- nest elements correctly
- frameset.dtd where required
- no empty lists
--no-timestamp prevents useless diff
--doc-files to dereference 1 level of softlinks (copy content instead of link)
--doc-relax prevents warnings if --doc-files do not exist
built scanner with bug-fixed fickle (http://www2.tcl.tk/3555)
allow @see without label
removed unnecessary backslashes that escaped #
removed misplaced "puts stderr" (a remainder when switching to tcldoc_error)
fixed erroneously flattened attributes (default values)

[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"
        }

Category Application

Category Dev. Tools

Category Documentation