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

2 files changed, 12 insertions, 2 deletions

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