summaryrefslogtreecommitdiffstats
path: root/doc/docblocks.doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/docblocks.doc')
-rw-r--r--doc/docblocks.doc74
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
+
*/