Release-1.4.4-20050806

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>.