Tydoc is the Tycho documentation system. $TYCHO/kernel/doc/codeDoc/index.html contains sample tydoc output.

Tydoc consists of two main parts:

TyDoc classes
The tydoc itcl classes DocSys, DocClass, ListDocSys and HTMLDocSys. These classes are defined in $TYCHO/lib/tydoc/TyDoc.itcl These classes could be used inside tycho for direct runtime conversion of Itcl files to html.
tydoc
A small standalone script that takes file names as command line arguments and converts the files to html output. For example tydoc DocSys.html would convert DocSys.html into four files, one for each class in the doc/codeDoc directory. If the doc/codeDoc directory does not exist, it is created. A index.html file is also created in the doc/codeDoc directory. The index.html file contains a menu with links to all of the class HTML files.

How it works

Tydoc reads in an Itcl file, protects the contents of the comments from interpretation, and then parses the file as a list into lists of different Itcl constructs. An Itcl construct is a part of the language like a class or method declaration.

To produce output in different formats, we have all of the format specific information a child class. Currently, we only generate HTML output, but it could be possible to write a Itcl pretty printer that would read in Itcl and output a cleaned up version.


Comment Format Conventions

Note: this should be merged into the Tycho coding style guide.

Tydoc depends on certain formatting conventions to grab comment information.

Comment formatting

In tcl, a comment line is a line that has a # as the first non-blank character. The symbol # is usually referred to as a hashmark, a poundsign or an octothorpe. In this document we refer to # as a hashmark.

Lines that contain more than one hashmark are not copied into the tydoc output.

A doc comment is a block of comments associated with a itcl construct. For a block of comments to be associated with a construct, there must be no blank lines between the block of comments and the construct.

A doc comment may contain doc tags, which consist of a tag and a value. For example, if we had a doc comment that looked like:

# @Author Tycho Brahe, Claudius Ptolemaus
Then @Author would be the tag, and Tycho Brahe, Claudius Ptolemaus would be the value.

The value of a doc tag consists of all text upto the next doc tag, or until the comment ends.

There are two types of doc tags, those that are file wide, and those that are only for one particular doc comment. (Note that much of the tag support is currently incomplete).

The text associated with a doc tag is assumed to be HTML source. However, to make writing comments a little simpler, tydoc applies some simple conversion rules to the text:

File-wide doc tags


@Author
A list of Authors.
@Version
Version Control System information, usually automatically generated by the version control system.
@Copyright
Copyright for this file.

Construct specific doc tags


@desc
The description of the construct. Usually a description is a short one line summary. The desc tag is optional if a doc comment has no tag, then the text is assumed to be a description.
@expl
The explanation of the construct. Usually an explanation is longer than the description.
If a construct is declared inside a class body, and then fully defined later in the file, outside of of a class body, usually the doc comment associated with the declaration would be a description, and the doc comment associated with the definition would be the explanation. If there is no expl doc tag in either doc comment, then we assume the above.

Constructs such as procs that are not part of a class end up in a file named ClassName_out.html, where ClassName is the name of the class defined in the file.

Tydoc output optimizations

The tydoc script takes a -v argument which will cause tydoc to generate output for all constructs in the file. If the -v option is not present, then the following constructs are not written to the html file:
  • All private constructs.
  • All option add constructs. In tycho, the options mechanism will be changing, and we don't want to document the current adhoc system.
  • All option constructs that are outside of a class.
  • constructors and destructors that don't have comments.
  • Another optimization that always happens is that only the first line of the @copyright doc comment is present in the html.

    tydoc and codeDoc.idx

    Classes can inherit from parent classes that are not necessarily in the current directory. To use create the proper links, tydoc uses the codeDoc.idx file.

    However, this represents a bit of a chicken and egg problem, as codeDoc.idx is based upon the tydoc output. The best solution is to create the tydoc output, then create codeDoc.idx and then recreate the tydoc output, which will use the codeDoc.idx to fix cross references. The following commands will do this for you:

    cd $TYCHO
    make itcldocs indices itcldocs
    

    Tycho Home Page.


    Copyright © 1996, The Regents of the University of California. All rights reserved.
    Last updated: 12/17/96, comments to: cxh@eecs.berkeley.edu