TclDoc - The Tcl API Documentation Generator

(TclDoc 0.87)

Generates HTML pages of API documentation from Tcl source files.


  1. Synopsis
  2. Description
    1. Terminology
  3. Source Files
    1. Tcl Procedure Source Code
    2. File Summary
    3. Overview Comment File
    4. Miscellaneous Unprocessed Files
  4. Generated Files
    1. Basic Content Pages
    2. Cross-Reference Pages
    3. Support Files
    4. Limitations
    5. HTML Frames
    6. HTML Format
  5. Documentation Comments
    1. Commenting a Procedure Source Code
    2. Commenting a File
    3. Using TclDoc Comments
  6. TclDoc Tags
  7. Where Tags Can Be Used
    1. File Overview Tags
    2. Procedure Documentation Tags
  8. Options


tcldoc [ options ] [ -- ] destination_dir @source

Arguments must be in this order.

Command-line options as specified in this document.
You may optionally mark the end of the options list with the special argument --. The following argument is inferred to be the destination directory. This is useful if the name of the destination begins with a dash.
Specifies the destination directory for newly generated files. If the directory does not exist TclDoc will automatically create it. Be sure that nothing important exists within the destination for TclDoc will overwrite the contents.
A series of source files or directories, separated by spaces, to analyze. If the argument specifies a directory TclDoc will scan for files ending in ".tcl" or ".tsh" and will recursively traverse any subdirectories within.


TclDoc parses the declarations and documentation comments in a set of Tcl source files and produces a corresponding set of HTML pages describing procedure declarations. Run TclDoc on a set of files and/or directories. It builds a rich internal representation of the files, determining both procedure declarations and procedure calls. TclDoc will run on .tcl and .tsh source files that are pure stub files with no procedure bodies. This means you can write documentation comments and run TclDoc in the earliest stages of design while creating the API, before writing the implementation.


A few terms have specific meanings within the context of TclDoc:
generated document
The document generated by the TclDoc tool from the comments in Tcl source code.
The name of a file being processed, excluding any path information. TclDoc is not designed to handle the situation where two files with the same name exist in different directories.
A procedure name. TclDoc can accomodate multiple procedure declarations, each of which is in a different file. If a file has multiple declarations for the same procedure TclDoc will give priority to the last one specified.


TclDoc will generate output originating from four different "sources": Tcl language source files for procedures (.tcl or .tsh), file-level summaries, overview comment file, and miscellaneous unprocessed files.

Tcl Procedure Source Code

Each procedure can have its own documentation comments contained in a .tcl or .tsh file. For more details about these doc comments see documentation comments and procedure tags.

File Summary

Each source code file can have its own documentation. Typically this is used to provide a summary of the procedures contained within. You may include special file overview tags within the description.

Overview Comment File

Instead of using the generated index as the "starting" page to the HTML files you may choose to design your own overview file. Typically this would include any documentation that applies to the entire application. There are two ways to insert an overview comment file:

Miscellaneous Unprocessed Files

You can also include in your source any miscellaneous files that you want TclDoc to copy to the destination directory. These could include graphic files, example Tcl sources, and self-standing HTML files whose content would overwhelm the documentation comment of a normal Tcl source file.

To include unprocessed files use the --doc-files option. Specify either a filename or an entire directory; TclDoc will then copy this file or directory to the destination. For many files you may find it more convenient to use the directory option, typically named doc-files. This directory may include subdirectories as needed; TclDoc will recursively copy subdirectories as well.

All links to these unprocessed files must be hard-coded because TclDoc does not examine the files; it simply copies them. For example, a link in a procedure comment might be:

# This button looks like this:
# <img src="doc-files/Button.gif">


TclDoc generates files with two types of names: those named after Tcl source code and those that are indices (such as index_annot.html). Files in the latter group contain underscores to prevent filename conflicts with those in the former group.

Basic Content Pages

Cross-Reference Pages

Support Files


In some cases the cross-reference pages do not document all the invocations since TclDoc does a static analysis of source code. For example procedure calls, which result from eval-statements, are not detected. In code where callback-handlers are bound to tk-widgets tclDoc will run into the same problem.

tclDoc resolves namespaces and document procedures, which are declared in different namespaces, correctly. But due to the fact that tcl offers namespaces which can be created or modified during runtime there is another reason why procedure calls may be undiscovered or procedure calls might be resolved incorrectly. Again the cross-reference pages might not be 100% reliable.

Furthermore tclDoc does not handle namespace-import-statements. The benefit would be very limited.

If you want to suppress generation of cross references use the --no-xref command line option.

HTML Frames

TclDoc will generate two HTML frames as shown in the figure below:


Load any of the index files, with the exception of index_main.html, as the starting page to enable HTML frames. Open any other files to have a frameless view.

HTML Format

The format of the generated files follow HTML 4.0. The Style ist defined by a default stylesheet based on CSS 2.0. The stylesheet named default.css is stored togehter with the generated files. By specifying a command line option you can use your own stylesheet. Copy the file default.css from the installation directory and use it as a template to create your own stylesheet.


Commenting Procedure Source Code

To enable TclDoc commands include documentation comments in the source code ahead of declarations for a procedure. These are also known as TclDoc comments. A procedure comment consists of all contiguous comment lines preceeding the hash symbol; there may not be any blank lines between the comment block and procedure declaration. In addition comment lines starting with at least three '-' are treated as empty comment lines. TclDoc requires that comments be on its own line with any number of preceeding whitespace. The following is an example of a legal procedure comment:

# -----------------------------------
  # Initialize the widget for the next use.
  # This must be done before using it else
  # mass hilarity ensues.
proc init_widget {} {
  # ...
Be aware that documentation comments placed in the procedure body are ignored.

Commenting a File

Commententing a file is similar to commenting a procedure. To differentiate between a doc comment for an entire file and a doc comment for the first procedure use the special sequence #//# to delimit the file-level comment. This sequence must be on its own line with any number of whitespace before the hash symbol.

#! /bin/bash
#  \
exec tclsh "$0" "$@"

# Here is where we discuss the file itself.
# ...

# This line summarizes procedure <code>foo<code>..
proc foo {} {
  # ...

File-level comments may reside anywhere within the file. If multiple blocks exist the last one takes precedence.

Using TclDoc Comments

A comment is a set of descriptions and tags - The description consists all text in the comment block excluding the comment character # and any initial whitespace. Certain character sequences, called tags, give the comment block a logical structure. With the exception of {@docroot} and {@link} all normal textual descriptions must reside before supplying any tags. There can be any number of tags in any order; some tags may be given multiple times. In the example below the first line is a description while the second is a tag.

# This is a doc comment.
# @see tk_optionMenu

Standard and in-line tags - A tag is a special keyword within a doc comment that TclDoc processes. TclDoc has standard tags which appear as @tag, and in-line tags which appear within braces as {@tag}. Normally standard tag appears at the beginning of a line, although nothing in TclDoc requires such. To prevent text from being interpreted as a tag use the HTML entity &#064; to represent the @ symbol. An in-line tag is allowed and interpreted anywhere that text is allowed; all other tags must be placed after normal text. The following example contains the standard tag @deprecated and in-line tag {@link}.

# @deprecated As of phil 3.9, replaced by {@link #lennie}

Comments are written in HTML - The text should be written in HTML, in that they should use HTML entities and can use HTML tags. You can use whichever version of HTML your browser supports.

For example entities for the less-than (<) and greater-than (>) symbols should be written &lt; and &gt;. Likewise, the ampersand (&) should be written &amp;. The HTML tags bold (<b>) and image (<img>) are shown in the following example.

# This is a <b>doc</b> comment.  We can even include
# our logo: <img src="logo.jpg" alt="Company Logo">.

Leading characters - When TclDoc parses a doc comment leading hash (#) characters on each line are discarded. Blanks and tabs preceding the # are also discarded.

First sentence - The first sentence of each doc comment should be a summary sentence containing a concise but complete description of the declared procedure. This sentence ends at the first period that is followed by a blank, tab, or line terminator. TclDoc will strip away all HTML tags from this first sentence prior to copying it to the file or procedure summary at the top of the annotated HTML page.

Use header tags carefully - When writing documentation comments for procedures it is best not to use HTML heading tags such as <H1> and <H2> because TclDoc creates an entire structured document and these structural markups may interfere with the formatting of the generated document. However it is fine to use these headings in file-level comments to provide your own structure.


TclDoc parses special tags when they are embedded within a Tcl doc comment. These doc tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with an "at" sign (@) and are case-sensitive; they must be typed in the lowercase letters as shown. Customarily tags start at the beginning of a line although this is not a requirement. By convention tags with the same name are grouped together. For example put all @see tags together.

The currently implemented tags are:
@author name-text
Adds an "Author" entry with the specified name-text to the generated docs when the -author option is used. A doc comment may contain multiple @author tags; TclDoc will concatenate all name-texts into one block.
Represents the relative path to the generated document's (destination) root directory from any generated page. It is useful when you want to include a file, such as a copyright page or company logo, that you want to reference from all generated pages. Including a company logo from the top of each page is common. A typical example might be:
# Built by <br>
# <center><img src="{@docRoot}/logo.jpg" alt="Logo"><br>
# Burdell Industries, Ltd.</center>
Althought TclDoc does not currently create separate directories for each package a future implementation might. Thus use of the {@docroot} tag is encouraged for future compatability.
@deprecated deprecated-text
Adds a comment indicating that this API should no longer be used (even though it may continue to work). TclDoc moves the deprecated-text ahead of the description placing it in italics and preceding it with a bold warning "Deprecated". The deprecated-text, if such exists, should tell the user when the API was deprecated and what to use as a replacement. Consider including a {@link} tag that points to the replacement API. If a doc comment has multiple @deprecated tags only the last one is used.
@exception exception-type description
Adds an Exception to the "Exceptions" section. Use a different @exception tag for each case an exception is raised. exception-type is the return code (i.e. the exceptional return code, see the tcl man pages of return and catch). e.g. TCL_ERROR, TCL_BREAK, TCL_CONTINUE etc. or an user defined integer if it is an user defined non-standard error.
{@link filename#procname label}
Inserts an in-line link with visible text label that points to the documentation for the specified filename or procedure declaration. This tag accepts exactly the same syntax for filename#procname and label as the @see tag, described below, but generates an in-line link rather than placing the link in the "See Also" section. This tag begins and ends with curly braces to separate it from the rest of the in-line text. If you need to use "}" inside the label use the HTML entity notation &#125;
There is no limit to the number of {@link} tags allowed in a sentence. You can use this tag in the description part of a documentation comment or in the text portion of any tag (such as @deprecated, @return or @param).
For example here is a comment that refers to the load procedure:
Use the {@link #load [load]} procedure.
From this, TclDoc would generate the following HTML (assuming the load function is declared within the same file):
Use the <a href="#load">[load]</a> procedure.
Which appears on the generated annotation page as:
Use the [load] procedure.
@param parameter-name description
Adds a parameter to the "Parameters" section. Use a different @param tag for each procedure argument.
@return description
Adds a "Returns" section with the description text. This text should describe the return type and permissible range of values. If a doc comment has multiple @return tags only the last one is used.
@see reference
Adds a "See Also" heading with a link or text entry that points to reference. A doc comment may contain any number of @see tags, which are all grouped under the same heading. The @see tag has four variations; the last two forms below are the most common.
@see "string"
Adds a text entry for string. No link is generated. The string should be a reference to information not available by URL. TclDoc distinguishes this from the other cases by looking for a double-quote (") as the first character. For example:
@see "The Tcl Programming Language"
This generates the following:
See Also:
"The Tcl Programming Language"
@see <a href="URL#value">label</a>
Adds a link as defined by URL#value. The URL#value is a relative or absolute URL. TclDoc distinguishes this from other cases by looking for a less-than symbol (<) as the first character. For example:
@see <a href="spec.html#section">Tcl Spec</a>
This generates a link such as:
See Also:
Tcl Spec
@see filename#procname label
Adds a link with visible text label that points to the documentation for the specified procedure name. The label is optional; if omitted, the name appears instead as the visible text. Use the label when you want the visible text to be abbreviated or different from the name. Labels may contain whitespace. TclDoc links to the file containing the first match. If no declaration was found then it will blindly create a hyperlink to the contents of filename.
Example - In this example the @see tag in the Widget file refers to the equal procedure in file String.tcl. The tag includes both arguments: the name "String.tcl#equal" and the label "equal".
# @see String.tcl#equal equal
TclDoc produces the HTML code:
<dt>See Also:</dt>
<dd><a href="String.tcl.html#equal">equal</a></dd>
which looks like:
See Also:
Specifying a name - The filename#procname, such as String.tcl#equal can be simplyfied if the procedure is defined in the same source file. In this case the filename and the # character can be skipped, e.g. such as equal or #equal. TclDoc than searches for the procedure within the same file. The procedure name procname need not contain the whole namespace path. TclDoc creates a hyperlink to the first procedure matching the given name. Otherwise if a filename is given TclDoc will determine where within the destination directory the file exists; usually this is the same directory, but may differ if to an imported file. If for some reason the given filename is unknown then the entire name is copied verbatim. An example utilizing this default behavior to link to an external page might be:
# @see overview.html#build_tree Tree Building
This generates the following HTML:
<dt>See Also:</dt>
<dd><a href="overview.html#build_tree">Tree Building</a></dd>
@see fullprocname label
This notation is similiar to the previous one. But by using this variant TclDoc checks for exact matching. fullprocname must be a full qualified procedure name, such as Simulator::Messaging::parseAFTN. If TclDoc does not find the procedure a warning is printed (use the command line option -v to see warnings).
@since since-text
Adds a "Since" heading with the specified since-text to the generated documentation. The text has no special internal structure. This tag means that this change or feature has existed since the software release specified by the since-text. Multiple @see tags may be specified possibly to indicate when certain features have been added. For example:
@since 1.3
@version version-text
Adds a "Version" subheading with the specified version-text to the generated output. The text has no special internal structure. A doc comment may contain multiple @version tag, which are grouped together into one block. Version normally refers to the version of the software that contains this file or procedure.


The following sections describe where the tags can be used.

File Overview Tags

File overviews may appear anywhere within the file. Subsequent overviews overwrite earlier ones. The following tags are allowed within the overview; others are ignored.

The file overview tags are:

An example of a file overview:

# This file contains procedures dealing with a button on the screen.
# For example:
# <pre>
#    button .b -text "Hello world"
#    pack .b
# </pre>
# @author    George P. Burdell
# @version   2.43.0
# @see       frame
# @see       wm

Procedure Documentation Tags

The following are tags that can appear in the documentation comment for a procedure declaration.

The procedure tags are:

An example of a procedure comment:

# Returns the character at the specified index.  An index
# ranges from <code>0</code> to <code>length() - 1</code>.
# @param  index the index of the desired character
# @exception TCL_ERROR index out of range
# @return the desired character
# @see    lists.tcl#lrange
proc lindex { s } {


Not done yet.


The TclDoc tool provides a set of command-line options that can be used to affect the output. All option names are case-sensitive.

The options are:
-f, --force
-h, --help
-v, --verbose
-w, --no-warn

General Options

-h, --help
Displays a brief summary of TclDoc's options.
-v, --verbose
Use this option to have TclDoc write to standard output its progress.
Tells TclDoc to write its version number to standard output.
-w, --no-warn
This option allows to switch off warnings. Only errors are reported. When verbose mode is enabled this option is ignored.
-f, --force
Prevents requesting confirmation before overwriting a pre-existing destination.
Marks End of Options.

Overall File Generation Options

--overview path/filename
Specifies that TclDoc should retrieve the text for the overview documentation from the "source" file specified by path/filename and places it as the overview page. The path/filename is relative to the current working directory. TclDoc accepts two kinds of overview files, regular HTML files and tcldoc-files. tcldoc-files must have the extension .tcldoc and must contain file comments.
While you can use any name you want for filename and place it anywhere a typical use is to name it overview.html and place it in the root directory of the source tree.
--doc-files path
If given a filename copies it to the destination directory. Otherwise if given a directory name designates it as the doc-files. The contents of this directory, including subdirectories, are copied verbatim to the destination. TclDoc will preserve the directory structure including keeping the tailing portion of the path. That is, the new directory's name will be that of all characters following the final directory separator within path, or path if it has no separator. Be aware that TclDoc will overwrite files in the destination directory. path may be either relative or absolute. Use this option multiple times to pull in additional files or directories.
prevents warnings if --doc-files do not exist
Disables copying the original source files to the destination directory to save disk space. Note that hyperlinks will still be generated to these non-existent files.
--title title
Sets the window title and the header for the main index.html page. Otherwise the window title defaults to "TclDoc Documentation" and the header is set to "TclDoc of destination-dir". The text may not contain HTML tags. So, in most cases it would be a good idea to set the title to something like "TclDoc of myPrettyProduct".
--header header
Specifies the header text to be placed above the navigation bar of each output file. header may contain HTML tags and white space, though if it does it must be enclosed in quotes. An example usage might be:
tclsh tcldoc.tcl --header '<span style="font-size:130%;">Sample Inc.</span> <em>foo API</em> v1.3' other options
--header-file filename
Same as --header but reads the header from file filename
--logo filename
Specifies an image file as a logo which is placed at the left in the header of the main pages - but not in the navigation bar. This file is copied to the destination directory.
--footer footer
Specifies the footer text to be placed beneath the navigation bar of each output file. footer may contain HTML tags and white space, though if it does it must be enclosed in quotes.
supresses generation of labels with timestamps. As long as sources are unchanged the generated documentation is always the same.
Disables showing the original path name of the Tcl source code in both the annotated view and annotation table of contents. Consider calling this option whenever displaying the path poses a security risk.
Prevents adding the navigation bar (Index by: file name | ...) at the top and bottom of marked-up source code pages, annotated pages, and the master index page. Navigation bars will still exist at the top of each individual index page.
Prevents generating an index for procedure calls.
Hides unexported procedures. Procedures defined within a nonglobal namespace but not exported by this namespace are not shown in the generated documentation.
Specifies an additional keyword which is used as a synonym for the keyword proc.
--date format
While generating the timestamp at the bottom of generated files TclDoc writes by default the date and time in ISO format. Use this option to specify an alternative format using any legal string as allowed by Tcl's [clock format] command. For example, the format string:
%h %e, %Y at %l:%M %p
yields the string Oct 22, 2004 at 3:36 PM.
--style file
Uses file as a user defined css-stylesheet instead of the default for all generated files. The referenced stylesheet is copied to the root of the generated document tree.
--charset charset
Uses charset in the html header of the generated html files. This only changes the declaration in the html-header. No translation of files will be done.

Import/Export Options

--import path/filename
Not implemented yet. Reads and parses a previously written export record. If the file does not exist, is unreadable, or in an invalid format, TclDoc will flag the error and terminate. See the --export option for details.
--include path/filename
Not implemented yet.
--exclude patternlist
Use this option to exclude files specified by a list of filenames or glob-style patterns. patternlist must be presented by a single argument.
tcldoc.tcl -f -title "my Program" --exclude '"./with spaces.tcl" */tclIndex' .
--export path/filename
Not implemented yet. One powerful feature of TclDoc is its ability to perform incremental commenting. After scanning Tcl files and generating the various files, TclDoc may write an export record to disk. This record holds a cache of calculated values from the program's execution. A future invocation of TclDoc may then consult this record, using the --import option, and build valid hyperlinks to the older files, just as if those older files were scanned along with the current ones. One reasonable example might be if a vendor ships a library along with its TclDoc documentation. The receiver might then want to generate its own documentation, linking its HTML files to the vendor's. Rather than re-running TclDoc on the vendor's files, the receiver could opt to --import the vendor-supplied export record. The export record holds the following values:
  1. A list of the names of all scanned files, and the location of their generated pages (which may be modified by the --export-loc option.
  2. A list of all found procedures, and their summary statements.
  3. A list of all calls to known procedures.
Note that if a TclDoc invocation imports a record, its export record will include values from the previous record.
--export-loc path/filename
Not implemented yet. When exporting records, sometimes it is desirable that hyperlinks to the generated files differ from the destination directory. Use this option to set the destination claimed within the export record. For example, one might want to build the TclDoc files into a temporary directory, but then later write them onto a CD-R. A future invocation of TclDoc might then want to hyperlink to those files on the CD-R via --import. Without the --export-loc option, the export record would still point to the temporary directory, which is no longer valid. Rather, the user should specify --export-loc path_to_CD-R during the first run of TclDoc so that the export record would claim the files reside on the CD-R instead of the temporary location. Note that using this option does not modify files generated during the current invocation of TclDoc. It only affects the export record.
--prune pathlist
Use this option to exclude whole directories specified by a list of pathnames. The list must be presented by a single argument e.g.
tcldoc.tcl -f  --title "my Program" --prune '"./with spaces" ./mytestprocs' .


GNU General Public License GPL V2. See


TclDoc is heavily influenced by the javadoc command. JavadocTM is a trademark of Sun Microsystems, Inc. The HTML page was based upon the documentaton for Javadoc later modified by Jason Tang and by Thomas Heinlein.