CODEWITHSUNDEEP
pythondoxygen
buhtz
buhtz

Reputation: 12152

How mark parameters in a python docstring for Doxygen

I am confused about the different styles about Python docstrings in the context of Doxygen. This makes it hard for me to decide if my style is wrong or if I just setup Doxygen the wrong way.

Let me give you an example of a style which is IMHO called Google Code Style.

def foobar_pargs(bar):
    """Package function with paramters.

    Paramters:
        bar (int): Parameter "bar" as type int.

    Returns:
        int: Value 7.
    """
    return 7

But I also see things like that with an @-sgin

def foobar_pargs(bar):
    """Package function with parameters.

    @param: bar (int): Parameter "bar" as type int.

    Returns:
        int: Value 7.
    """
    return 7

I am using Doxygen from git with set settings.

# Difference with default Doxyfile 1.9.4 (57efad44bfc02744ba5fd8ea820b54a2443e3771)
PROJECT_NAME           = "Doxygen Example"
OPTIMIZE_OUTPUT_JAVA   = YES
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_PACKAGE        = YES
EXTRACT_STATIC         = YES
EXTRACT_LOCAL_METHODS  = YES
SORT_MEMBER_DOCS       = NO
WARN_NO_PARAMDOC       = YES
INPUT                  = ../src/doxygen_example
FILE_PATTERNS          =
RECURSIVE              = YES
EXCLUDE                = ./_trash
EXAMPLE_PATTERNS       =
FILTER_PATTERNS        = *.py=./py_filter
HTML_TIMESTAMP         = YES
GENERATE_TREEVIEW      = YES
MATHJAX_RELPATH        = https://cdn.jsdelivr.net/npm/mathjax@2
GENERATE_LATEX         = NO
HAVE_DOT               = YES
UML_LOOK               = YES
DOT_UML_DETAILS        = YES

And also PYTHON_DOCSTRING = YES (which is default in Doxygen). I also setup doxypypy (which you can see at FILTER_PATTERNS).

Which way should I go?

The resulting html looks like this and is quit ugly when rendered.

<p>This is a methode with parameters. </p>
<dl class="section user"><dt>Parameters</dt><dd>a A string. b A float value.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd></dd>
<dd>
str Value of 'b' as string.</dd></dl>
<dl class="exception"><dt>Exceptions</dt><dd>
  <table class="exception">
    <tr><td class="paramname">ValueError</td><td>If b is less then 0. </td></tr>
  </table>
  </dd>
</dl>

Upvotes: 1

Views: 1238

Answers (1)

albert
albert

Reputation: 9012

There are no real facilities for parameters to have a type as for C / C++ functions etc. the type directly follows from the function prototype / definition.

In python one could look for the newer functionalities of type decorators in the def statement.

For the given example I would do something like:

## \file


def foobar_pargs(bar):
   """
    @brief Package function with parameters.

    @param bar (int): Parameter "bar" as type int.

    @returns int: Value 7.
   """
  return 7

with the setting:

PYTHON_DOCSTRING = NO

Upvotes: 1

Related Questions