AutoDoc's view of the world is very simple. It is given a single directory, which serves as starting point for the distribution to be scanned. A distribution is seen as collection of packages, these then contain the tcl code to be analysed. In case of no packages found the engine assumes that the whole distribution is a single unnamed package. Why is this important, some might ask. Well, the engine will search only the directories containing packages for files containing tcl code. Everything else is left out. Except if there are no explicit packages. The assumption told of before then causes search of the entire tree.
Packages are detected by the presence of a file named pkg.doc in a directory. It is sourced, the description contained will be integrated into the HTML pages later. See lib/pkg.doc of this distribution for an example.
The engine assumes that all files with extensions '.tcl' or '.cls' contain tcl code to be analysed, but no more. '.cls'-files are the ones I use to store class definitions based on the OO framework of Pool. They get separate files as I use a tcl-based compiler to convert such definitions into pure tcl code, the resulting files get the usual extension, aka '.tcl'. Another behaviour caused by this: If two files X.cls and X.tcl are found the latter one will be skipped, assuming that it was/will be generated out of the former. Package indices (pkgIndex.tcl) are recognized and will be skipped too.
Some more files are recognized, but I delay explanation of purpose and usage until we talk about integration of manually (or semi-automatically) written html pages.
Back to the files with tcl code. Their documentation is searched in the top/first chunk of comments only. The first non-comment line will stop the search. The same holds for class definitions, only the chunk of comments at the very beginning is searched. On the other hand the whole body of a procedure is searched for embedded documentation commands.
The engine recognizes 'package require' commands and uses them to track dependencies on external packages. For every detected package X an external reference extpkg_X is searched for (See integration for more information about such). If present, the reference is used to insert an appropriate hyperlink into the generated pages. Without such a reference plain text is used to display the dependency. To help the user in providing this references all dependencies without such are logged with a warning.
As for the output, it is generally structured like
Generated by AutoDoc 2.4 at 09/28/2001, invoked by Andreas Kupries,,,