diff options
| -rw-r--r-- | doc/docblocks.doc | 10 | ||||
| -rw-r--r-- | src/config.xml | 10 | ||||
| -rw-r--r-- | src/pyscanner.l | 4 |
3 files changed, 19 insertions, 5 deletions
diff --git a/doc/docblocks.doc b/doc/docblocks.doc index 6c1edae..96a2621 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 29f4068..b3718be 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 017cc03..d7996b4 100644 --- a/src/pyscanner.l +++ b/src/pyscanner.l @@ -1682,7 +1682,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->commentIndent = yyextra->curIndent; yyextra->doubleQuote = TRUE; @@ -1695,7 +1695,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->commentIndent = yyextra->curIndent; yyextra->doubleQuote = FALSE; |