diff options
Diffstat (limited to 'doc/docblocks.doc')
| -rw-r--r-- | doc/docblocks.doc | 74 |
1 files changed, 71 insertions, 3 deletions
diff --git a/doc/docblocks.doc b/doc/docblocks.doc index e28328c..ea51edd 100644 --- a/doc/docblocks.doc +++ b/doc/docblocks.doc @@ -20,9 +20,10 @@ A special documentation block is a C or C++ style comment block with some additional markings, so doxygen knows it is a piece of documentation that -needs to end up in the generated documentation. For Python, VHDL, and Fortran -code there are different comment conventions, which can be found in sections -\ref pythonblocks, \ref vhdlblocks, and \ref fortranblocks respectively. +needs to end up in the generated documentation. For Python, VHDL, Fortran, and +Tcl code there are different comment conventions, which can be found in sections +\ref pythonblocks, \ref vhdlblocks, \ref fortranblocks, and \ref tclblocks +respectively. For each code item there are two (or in some cases three) types of descriptions, which together form the documentation: a \e brief description and \e detailed @@ -480,4 +481,71 @@ C> input parameter end function A \endverbatim +\section tclblocks Documentation blocks in Tcl + +Doxygen documentation can be included in normal Tcl comments. + +To start a new documentation block start a line with \c ## (two hashes). +All following comment lines and continuation lines will be added to this +block. The block ends with a line not starting with a \c # (hash sign). + +A brief documentation can be added with \c ;#< (semicolon, hash and +lower then sign). The brief documentation also ends at a line not starting +with a \c # (hash sign). + +Inside doxygen comment blocks all normal doxygen markings are supported. +The only expections are described in the following two paragraphs. + +If a doxygen comment block ends with a line containing only +\c #\\code or \c #\@code all code until a line only containing \c #\\endcode +or \c #\@endcode is added to the generated documentation as code block. + +If a doxygen comment block ends with a line containing only +\c #\\verbatim or \c #\@verbatim all code until a line only containing +\c #\\endverbatim or \c #\@endverbatim is added verbatim to the generated +documentation. + +To detect namespaces, classes, functions and variables the following +Tcl commands are recognized. Documentation blocks can be put on the lines +before the command. + +<ul> +<li><tt>namespace eval ..</tt> Namespace +<li><tt>proc ..</tt> Function +<li><tt>variable ..</tt> Variable +<li><tt>common ..</tt> Common variable +<li><tt>itcl::class ..</tt> Class +<li><tt>itcl::body ..</tt> Class method body definition +<li><tt>oo::class create ..</tt> Class +<li><tt>oo::define ..</tt> OO Class definition +<li><tt>method ..</tt> Class method definitions +<li><tt>constructor ..</tt> Class constructor +<li><tt>destructor ..</tt> Class destructor +<li><tt>public ..</tt> Set protection level +<li><tt>protected ..</tt> Set protection level +<li><tt>private ..</tt> Set protection level +</ul> + +<!-- +To use your own keywords you an map these keyword to the recognized commands +using the \ref cfg_tcl_subs "TCL_SUBST" entry in the config file. +The entry contain a list of word-keyword mappings. To use the itcl::* +commands without the leading namespace use p.e.: + +\verbatim TCL_SUBST = class itcl:class body itcl:body \endverbatim +--> + +Following is a example using doxygen style comments: + +\include tclexample.tcl + \htmlonly + Click <a href="$(DOXYGEN_DOCDIR)/examples/tclexample/html/index.html">here</a> + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + +\htmlonly +Go to the <a href="lists.html">next</a> section or return to the + <a href="index.html">index</a>. +\endhtmlonly + */ |