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

3 files changed, 19 insertions, 5 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 
diff --git a/src/config.xml b/src/config.xml
index f40744d..7f26ea9 100644
--- a/src/config.xml
+++ b/src/config.xml
@@ -513,6 +513,16 @@ Go to the <a href="commands.html">next</a> section or return to the
 ]]>
       </docs>
     </option>
+    <option type='bool' id='PYTHON_DOCSTRING' defval='1'>
+      <docs>
+<![CDATA[
+  By default Python docstrings are displayed as preformatted text
+  and doxygen's special commands cannot be used. By setting \c PYTHON_DOCSTRING to
+  \c NO the doxygen's special commands can be used and the contents of the docstring
+  documentation blocks is shown as doxygen documentation.
+]]>
+      </docs>
+    </option>
     <option type='bool' id='INHERIT_DOCS' defval='1'>
       <docs>
 <![CDATA[
diff --git a/src/pyscanner.l b/src/pyscanner.l
index e5f4073..8230b86 100644
--- a/src/pyscanner.l
+++ b/src/pyscanner.l
@@ -1670,7 +1670,7 @@ static void initTriDoubleQuoteBlock(yyscan_t yyscanner)
   yyextra->docBlockContext   = YY_START;
   yyextra->docBlockInBody    = FALSE;
   yyextra->docBlockJavaStyle = TRUE;
-  yyextra->docBlockSpecial   = yytext[strlen(yytext) - 1]=='!';
+  yyextra->docBlockSpecial   = yytext[strlen(yytext) - 1]=='!' || !Config_getBool(PYTHON_DOCSTRING);
   yyextra->docBlock.resize(0);
   yyextra->doubleQuote = TRUE;
   startCommentBlock(yyscanner,FALSE);
@@ -1682,7 +1682,7 @@ static void initTriSingleQuoteBlock(yyscan_t yyscanner)
   yyextra->docBlockContext   = YY_START;
   yyextra->docBlockInBody    = FALSE;
   yyextra->docBlockJavaStyle = TRUE;
-  yyextra->docBlockSpecial   = yytext[strlen(yytext) - 1]=='!';
+  yyextra->docBlockSpecial   = yytext[strlen(yytext) - 1]=='!' || !Config_getBool(PYTHON_DOCSTRING);
   yyextra->docBlock.resize(0);
   yyextra->doubleQuote = FALSE;
   startCommentBlock(yyscanner,FALSE);