summaryrefslogtreecommitdiffstats
path: root/doc/docblocks.doc
diff options
context:
space:
mode:
authordimitri <dimitri@afe2bf4a-e733-0410-8a33-86f594647bc7>2007-07-27 08:53:22 (GMT)
committerdimitri <dimitri@afe2bf4a-e733-0410-8a33-86f594647bc7>2007-07-27 08:53:22 (GMT)
commitcfa9d4d590cdbf4940f88159f72853e8501cc168 (patch)
tree096d7be65663d2b1088aed9714e8047edf65961d /doc/docblocks.doc
parent54e919c70d5a43e260b188d5c71fd7c54ce874f0 (diff)
downloadDoxygen-cfa9d4d590cdbf4940f88159f72853e8501cc168.zip
Doxygen-cfa9d4d590cdbf4940f88159f72853e8501cc168.tar.gz
Doxygen-cfa9d4d590cdbf4940f88159f72853e8501cc168.tar.bz2
Release-1.5.3
Diffstat (limited to 'doc/docblocks.doc')
-rw-r--r--doc/docblocks.doc27
1 files changed, 21 insertions, 6 deletions
diff --git a/doc/docblocks.doc b/doc/docblocks.doc
index d5ff845..d364858 100644
--- a/doc/docblocks.doc
+++ b/doc/docblocks.doc
@@ -24,15 +24,21 @@ needs to end up in the generated documentation. For Python code there is
a different comment convention, which can be found in section
\ref pythonblocks
-For each code item there are two types of descriptions, which together
-form the documentation: a \e brief description and \e detailed
-description, both are optional.
-Having more than one brief or detailed description however, is
-not allowed.
+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
+description, both are optional. For methods and functions there is also a third
+type of description, the so called "in body" description, which consists of
+the concatenation of all comment blocks found within the body of the method or function.
+
+Having more than one brief or detailed description is allowed (but not recommended,
+as the order in which the descriptions will appear is not specified).
As the name suggest, a brief description is
a short one-liner, whereas the detailed description provides longer,
-more detailed documentation.
+more detailed documentation. An "in body" description can also act as a detailed
+description or can describe a collection of implementation details.
+For the HTML output brief descriptions are also
+use to provide tooltips at places where an item is referenced.
There are several ways to mark a comment block as a detailed description:
<ol>
@@ -87,6 +93,15 @@ or
Some people like to make their comment blocks more visible in the
documentation. For this purpose you can use the following:
+
+\verbatim
+/************************************************
+ * ... text
+ ***********************************************/
+\endverbatim
+
+or
+
\verbatim
/////////////////////////////////////////////////
/// ... text ...