summaryrefslogtreecommitdiffstats
path: root/doc/docblocks.doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/docblocks.doc')
-rw-r--r--doc/docblocks.doc49
1 files changed, 43 insertions, 6 deletions
diff --git a/doc/docblocks.doc b/doc/docblocks.doc
index b1ad2dc..a0132d8 100644
--- a/doc/docblocks.doc
+++ b/doc/docblocks.doc
@@ -18,9 +18,11 @@
\section specialblock Special documentation blocks
-A special documentation block is a C or C++ comment block with some
+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.
+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
@@ -168,7 +170,7 @@ detailed description, the one before the \e definition is preferred
and the one before the declaration will be ignored.
Here is an example of a documented piece of C++ code using the Qt style:
-\verbinclude qtstyle.cpp
+\include qtstyle.cpp
\htmlonly
Click <a href="$(DOXYGEN_DOCDIR)/examples/qtstyle/html/class_test.html">here</a>
for the corresponding HTML documentation that is generated by doxygen.
@@ -201,7 +203,7 @@ Here is an example:
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
+\include 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.
@@ -260,7 +262,7 @@ only the \< indicates that the member is
located in front of the block instead of after the block.
Here is an example of the use of these comment blocks:
-\verbinclude afterdoc.h
+\include afterdoc.h
\htmlonly
Click <a href="$(DOXYGEN_DOCDIR)/examples/afterdoc/html/class_test.html">here</a>
for the corresponding HTML documentation that is generated by doxygen.
@@ -313,6 +315,7 @@ Other structural commands are:
<li>\c \\fn to document a function.
<li>\c \\var to document a variable or typedef or enum value.
<li>\c \\def to document a \#define.
+<li>\c \\typedef to document a type definition.
<li>\c \\file to document a file.
<li>\c \\namespace to document a namespace.
<li>\c \\package to document a Java package.
@@ -335,7 +338,7 @@ or a \verbatim /** @file */ \endverbatim line in this file.
Here is an example of a C header named \c structcmd.h that is documented
using structural commands:
-\verbinclude structcmd.h
+\include structcmd.h
\htmlonly
Click <a href="$(DOXYGEN_DOCDIR)/examples/structcmd/html/structcmd_8h.html">here</a>
for the corresponding HTML documentation that is generated by doxygen.
@@ -351,6 +354,40 @@ using structural commands:
in comment blocks which are place in front of a function. This is clearly
a case where the \\fn command is redundant and will only lead to problems.
+\section pythonblocks Special documentation blocks in Python
+
+For Python there is a standard way of documenting the code using
+so called documentation strings. Such strings are stored in \c __doc__
+and can be retrieved at runtime. Doxygen will extract such comments
+and assume they have to be represented in a preformatted way.
+
+\include docstring.py
+ \htmlonly
+ Click <a href="$(DOXYGEN_DOCDIR)/examples/docstring/html/index.html">here</a>
+ for the corresponding HTML documentation that is generated by doxygen.
+ \endhtmlonly
+
+Note that in this case none of doxygen's \ref cmd_intro "special commands"
+are supported.
+
+There is also another way to document Python code using comments that
+start with "##". These type of comment blocks are more in line with the
+way documentation blocks work for the other languages support doxygen
+and this also allows the use of special commands.
+
+Here is the same example again but now using doxygen style comments:
+
+\include pyexample.py
+ \htmlonly
+ Click <a href="$(DOXYGEN_DOCDIR)/examples/pyexample/html/index.html">here</a>
+ for the corresponding HTML documentation that is generated by doxygen.
+ \endhtmlonly
+
+Since python looks more like Java than like C or C++, you should set
+\ref cfg_optimize_output_java "OPTMIZE_OUTPUT_JAVA" to \c YES in the
+config file.
+
+
\htmlonly
Go to the <a href="lists.html">next</a> section or return to the
<a href="index.html">index</a>.