Using Python docstrings

- making documentation a bit clearer
- add configuration setting to have docstrings not as preformatted text but as normal documentation (default remains preformatted).

1 files changed, 7 insertions, 3 deletions

diff --git a/doc/docblocks.doc b/doc/docblocks.doc
index 23933c7..d6d8fae 100644
--- a/doc/docblocks.doc
+++ b/doc/docblocks.doc
@@ -450,7 +450,7 @@ the script can be found in the path set via \ref cfg_example_path "EXAMPLE_PATH"
 \subsection pythonblocks Comment 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__
+so called documentation strings (<tt>"""</tt>). 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.
 
@@ -464,8 +464,12 @@ and assume they have to be represented in a preformatted way.
  for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
  \endlatexonly
 
-Note that in this case none of doxygen's \ref cmd_intro "special commands" 
-are supported.
+\note When using <tt>\"\"\"</tt> none of doxygen's \ref cmd_intro "special commands" 
+are supported and the text is shown as verbatim text see \ref cmdverbatim "\\verbatim".
+To have the doxygen's \ref cmd_intro "special commands" and have the text as regular
+documentation instead of <tt>\"\"\"</tt> use <tt>\"\"\"!</tt> or set 
+\ref cfg_python_docstring "PYTHON_DOCSTRING" to \c NO in the configuration file.
+\note Instead of <tt>\"\"\"</tt> one can also use <tt>'''</tt>.
 
 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