$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 methodfred
uses 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 proc
s 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