如何在 Doxygen 的 python 文档字符串中标记参数

Question

我对 Doxygen 上下文中 Python 文档字符串的不同风格感到困惑。这让我很难决定是我的风格错误还是我只是以错误的方式设置了 Doxygen。

让我举一个例子，恕我直言，它被称为 Google 代码风格。

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

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

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

但我也看到了类似 @-sgin

的事情

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

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

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

我正在使用 git 的 Doxygen 并进行设置。

# 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

还有PYTHON_DOCSTRING = YES（Doxygen 中的默认值）。我还设置了 doxypypy（您可以在 FILTER_PATTERNS 看到）。

我应该走哪条路？

生成的 html 看起来像这样，渲染时非常丑陋。

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

Answer 1

对于 C/C++ 函数等，参数没有类型的真正设施。类型直接来自函数原型/定义。

在 python 中，可以在 def 语句中寻找类型装饰器的新功能。

对于给定的例子，我会做类似的事情：

## \file


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

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

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

设置：

PYTHON_DOCSTRING = NO

如何在 Doxygen 的 python 文档字符串中标记参数

How mark parameters in a python docstring for Doxygen

python

doxygen