summaryrefslogtreecommitdiffstats
path: root/doc/docblocks.doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/docblocks.doc')
-rw-r--r--doc/docblocks.doc42
1 files changed, 21 insertions, 21 deletions
diff --git a/doc/docblocks.doc b/doc/docblocks.doc
index e0c9161..804187a 100644
--- a/doc/docblocks.doc
+++ b/doc/docblocks.doc
@@ -63,40 +63,32 @@ In both cases the intermediate *'s are optional, so
is also valid.
<li> A third alternative is to use a block of at least two C++ comment
-lines, where the first starts with an additional slash or an
+lines, where each line starts with an additional slash or an
exclamation mark. Here are examples of the two cases:
\verbatim
///
-// ... text ...
-//
+/// ... text ...
+///
\endverbatim
or
\verbatim
//!
-// ... text ...
-//
+//!... text ...
+//!
\endverbatim
<li>
-One could also repeat the special markers for each line as shown in
-the following examples:
-
-\verbatim
-///
-/// ... text ....
-///
-\endverbatim
-
-or
+Some people like to make their comment blocks more visible in the
+documentation. For this purpose you can use the following:
\verbatim
-//!
-//! ... text ...
-//!
+/////////////////////////////////////////////////
+/// ... text ...
+/////////////////////////////////////////////////
\endverbatim
</ol>
@@ -117,7 +109,8 @@ Here is an example:
*/
\endverbatim
-<li>If \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" is set to YES in the configuration file,
+<li>If \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" is set to \c YES
+ in the configuration file,
then using JavaDoc style comment
blocks will automatically start a brief description which ends at the
first dot followed by a space or new line. Here is an example:
@@ -127,6 +120,11 @@ Here is an example:
* here.
*/
\endverbatim
+The option has the same effect for multi-line special C++ comments:
+\verbatim
+/// Brief description which ends at this dot. Details follow
+/// here.
+\endverbatim
<li>A third option is to use a special C++ style comment which does not
span more than one line. Here are two examples:
@@ -145,7 +143,9 @@ or
\endverbatim
Note the blank line in the last example, which is required to separate the
-brief description from the block containing the detailed description.
+brief description from the block containing the detailed description. The
+\ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" should also be set to \c NO
+for this case.
</ol>
@@ -215,7 +215,7 @@ implementer of the members more direct access to the documentation.
As a compromise the brief description could be placed before the
declaration and the detailed description before the member definition.
-\subsection memberdoc Documenting members afterwards
+\subsection memberdoc Putting documentation after members
If you want to document the members of a file, struct, union, class, or enum,
and you want to put the documentation for these members inside the compound,