如何用参数记录方法？ [英] How to document a method with parameter(s)?

问题描述

如何使用Python的文档字符串来记录带有参数的方法？

编辑：
< a href = http://www.python.org/dev/peps/pep-0257/ rel = noreferrer> PEP 257 给出了以下示例：

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

这是大多数Python开发人员使用的约定吗？

Is this the convention used by most Python developers ?

Keyword arguments:
<parameter name> -- Definition (default value if any)

我期待一些更正式的内容，例如

I was expecting something a little bit more formal such as

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    @param: real The real part (default 0.0)
    @param: imag The imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

环境：Python 2.7.1

Environment: Python 2.7.1

推荐答案

根据我的经验， numpy docstring约定（PEP257超集）是使用最广泛的 followed 约定也受 Sphinx 之类的工具的支持。

Based on my experience, the numpy docstring conventions (PEP257 superset) are the most widely-spread followed conventions that are also supported by tools, such as Sphinx.

一个例子：

Parameters
----------
x : type
    Description of parameter `x`.

这篇关于如何用参数记录方法？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！