diff options
Diffstat (limited to 'doc/docblocks.doc')
| -rw-r--r-- | doc/docblocks.doc | 31 |
1 files changed, 15 insertions, 16 deletions
diff --git a/doc/docblocks.doc b/doc/docblocks.doc index 3ac2789..7500eb5 100644 --- a/doc/docblocks.doc +++ b/doc/docblocks.doc @@ -66,34 +66,33 @@ sentence of the detailed description to \c NO). Both the brief and the detailed descriptions are optional for the Qt style. -Here is the same piece of code, this time documented using the JavaDoc -style: +By default a JavaDoc style documentation block behaves the same way as a +Qt style documentation block. This is not according the JavaDoc specification +however, where the first sentence of the documentation block is automatically +treated as a brief description. To enable this behaviour you should set +\ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" to YES in the configuration +file. If you enble this option and want to put a dot in the middle of a +sentence without ending it, you should put a backslash and a space after it. +Here is an example: +\verbatim + /** Brief description (e.g.\ using only a few words). Details follow. */ +\endverbatim + +Here is the same piece of code as shown above, this time documented using the +JavaDoc style and \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" set to YES: \verbinclude jdstyle.cpp \htmlonly Click <a href="$(DOXYGEN_DOCDIR)/examples/jdstyle/html/class_test.html">here</a> for the corresponding HTML documentation that is generated by doxygen. \endhtmlonly -Note that by default the first sentence of the documentation (until the <tt>.</tt>) -is treated as a brief description, whereas the documentation block as a whole -forms the detailed description. If you want to put a dot in the middle of a -sentence you should put a backslash and space behind it. Example: -\verbatim - /** Brief description (e.g.\ using only a few words). Details follow. */ -\endverbatim -The brief description is required for the JavaDoc style, unless you set -\ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" to NO. If you do this, -doxygen treats JavaDoc comments just like Qt comments (i.e. You have -to insert an explicit \ref cmdbrief "\\brief" command to add a brief description). - Unlike most other documentation systems, doxygen also allows you to put the documentation of members (including global functions) in front of the \e definition. This way the documentation can be placed in the source file instead of the header file. This keeps the header file compact, and allows the 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 -(assuming you use the Qt style comments). +declaration and the detailed description before the member definition. \par Note: Each entity can only have \e one brief and \e one detailed description. If you |