$TYCHO/kernel/doc/codeDoc/index.html contains
sample tydoc output.
Tydoc consists of two main parts:
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 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.
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.
Tydoc depends on certain formatting conventions to grab comment information.
# 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 PtolemausThen
@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:
_I_ think this is a _perfectly reasonable convention_!will be converted into
<i>I</i> think this is a <i>perfectly reasonable convention</i>!
I think this is a perfectly reasonable convention!
The method fred{} uses the global variable *rightSaid*.will be converted into
The method <code>fred<code> uses the global variable <code>rightSaid</code>.
The methodfreduses the global variablerightSaid.
@Author
@Version
@Copyright
@desc
desc tag is
optional if a doc comment has no tag, then the text is assumed
to be a description.
@expl
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 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:
Another optimization that always happens is that only the first line of the @copyright doc comment is present in the html.
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