TclDoc-The Tcl API Documentation Generator

# TclDoc - The Tcl API Documentation Generator

> Generates HTML pages of API documentation from Tcl source files.

## CONTENTS

- Synopsis
- Description
  - Terminology
- Source Files
  - Tcl Procedure Source Code
  - File Summary
  - Overview Comment File
  - Miscellaneous Unprocessed Files
- Generated Files
  - Basic Content Pages
  - Cross-Reference Pages
  - Support Files
- Documentation Comments
  - Commenting a Procedure Source Code
  - Commenting a File
  - Using TclDoc Comments
- TclDoc Tags
- Where Tags Can Be Used
  - File Overview Tags
  - Procedure Documentation Tags
- Options

## SYNOPSIS

> `tcldoc [ options ] [ -- ] destination_dir @source`

> Arguments must be in this order.

> > `options`
> >   Command-line options as specified in this document. To see a typical use of TclDoc options see Real-World Example.
> > `--`
> >   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.
> > `destination_dir`
> >   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.
> > `@source`
> >   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.

## DESCRIPTION

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

> ### Terminology

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

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

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

## SOURCE FILES

> 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. To create an overview comment file give it a name (such as overview.html), place it somewhere (typically at the top level of the source tree), then while running TclDoc to specify this overview file with the `--overview` option. TclDoc does not process this file in any way; it merely copies it over to the destination directory and link to the copy.

> ### 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 includes graphic files, example Tcl source, 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">

## GENERATED FILES

> 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

> - One marked-up source code page (filename`.html`) for each source file it is documenting. TclDoc adds three types of mark-ups per source file. First it creates hyperlinks from procedure calls to their definitions. If the definition is not within the same file TclDoc will search through all other scanned files for it. Second it hyperlinks the procedure definition itself to its annotated entry (see below). Third TclDoc highlights comments with a different color.
> - One annotated page (filename`-annot.html`) for each source file. TclDoc scans comment blocks for special TclDoc tags which are collected to form the annotated source page.
> - One original code page (filename`.txt`) which is merely a copy of the original source file. TclDoc may be configured to skip this if given the `--dont-copy` option.

> Cross-Reference Pages

> - One filename index page (`index_file.html`). This page alphabetically lists all scanned files and the procedures declared in each. Procedure names are hyperlinked to the declarations on their respective marked-up source page.
> - One procedure declaration index page (`index_proc.html`) consisting of all procedure declarations alphabetically listed. Again, each entry is hyperlinked to its respective marked-up source page. If a procedure is declared in multiple files the index includes each definition. For multiple declarations within the same file this index will link to the last instance.
> - One procedure call index page (`index_call.html`). This index lists all instances of a procedure being called, either within the same file or from a different file. The entries are hyperlinked to the line within the marked-up source page which makes the call.
> - One master page (`index_main.html`) formed by the concatenation of the three previous indices.
> - One annotation index page (`index_annot.html`) that alphabetically lists all declared procedures and filenames. Each item is hyperlinked to the description on their respective annotated page.
> - One annotation table of contents page (`index_annot_full.html`) that gives a listing of all declared procedure and filenames as well as their summary statements.

> Support Files

> - One index.html file which creates the HTML frames for display. This is the file you load to display the front page with frames. The file itself contains no textual content.
> - One overview page, if given as an option to TclDoc via the `--overview` option.
> - One or more doc-files directory that holds any image, example source code, or other files that you want copied to the destination directory. These files are not processed by TclDoc in any manner -- that is, any TclDoc tags in them will be ignored. This directory is not generated unless specified with the `--doc-files` option and a directory name is given.
> - One export record if specified on the command line with the `--export` option. See the section on exporting for details. FIX ME!

> HTML Frames

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

> >     ----------------
> >     | I |  Detail  |
> >     | n |          |
> >     | d |          |
> >     | e |          |
> >     | x |          |
> >     |   |          |
> >     ----------------

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

## DOCUMENTATION COMMENTS

> ### 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 betweent the comment block and procedure declaration. 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.

> >     #//#
> >     # 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 TAGS

> 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 implementd tags are:

> - `@author`
> - `{@docroot}`
> - `@deprecated`
> - `{@link}`
> - `@param`
> - `@return`
> - `@see`
> - `@since`
> - `@version`
> `@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.

> `{@docRoot}`
>   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.

> `{@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 three variations; the third form below is 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 Specs</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:

>     >     <dl>
>     >     <dt><strong>See Also:</strong>
>     >     <dd><a href="String.tcl.html#equal">equal</a>
>     >     </dl>

>     which looks like:

>     > See Also:
>     >   equals

>     Specifying a name - The filename`#`procname name can be either fully-qualified, such as `String.tcl#equal` or be just a procedure name, such as `equal` or `#equal`. If less than fully-qualified, TclDoc assumes the procedure is declared within the same file and will create an appropriate hyperlink. 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:

>     >     <dl>
>     >     <dt><strong>See Also:</strong>
>     >     <dd><a href="overview.html#build_tree">Tree Building</a>
>     >     </dl>

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

## WHERE TAGS CAN BE USED

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

> File Overview Tags
> `@see`
> `{@link}`
> `@since`
> `@deprecated`
> `@author`
> `@version`
> `{@docRoot}`

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

> Procedure Tags
> `@see`
> `{@link}`
> `@since`
> `@deprecated`
> `@param`
> `@return`
> `@author`
> `@version`
> `{@docRoot}`

> #### 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
>     # @return the desired character
>     # @see    lists.tcl#lrange
>     proc lindex { s } {
>         ...
>     }

## IMPORTING AND EXPORTING RECORDS

> Not done yet.

## OPTIONS

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

> > --comment --date --doc-files --dont-copy --export | --export-loc -f, --footer --force --header -h, --help | --hide-paths --import --include --no-navbar --overview | --page-bg --table-bg -v, --verbose --title

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

> -f, --force
>   Prevents requesting confirmation before overwriting a pre-existing destination.

> --overview path/filename
>   Specifies that TclDoc should retrieve the text for theoverview 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.

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

> --dont-copy
>   Disables copying the original source files to the destination directory to save disk space. Note that hyperlinks will still be generated to these non-existant files.

> --title title
>   Sets the title for the main `index.html` page. Otherwise it defaults to `TclDoc Documentation`.

> --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 "<em>My API</em><br>v1.3" other options`

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

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

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

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

> --comment color
>   Sets the foreground color used to highlight comments within marked-up source code. Give the color as a set of six hexadecimal digits. The default color, a pale green, is the value `208020`.

> --page-bg color
>   Sets the background color for all generated files. Give the color as a set of six hexadecimal digits. The default color, white, is the value `ffffff`.

> --table-bg color
>   Sets the background color for the table headers on annotated pages. Give the color as a set of six hexadecimal digits. The default color, a pale blue, is the value `ccccff`.

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

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

## LICENSE

> GPL blah

## ACKNOWLEDGEMENT

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.