python - 如何用参数记录方法？

Question

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

编辑: 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 开发人员使用的约定吗？

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

我期待一些更正式的东西，例如

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

Answer 1

由于文档字符串是自由格式的，它实际上取决于您使用什么来解析代码以生成 API 文档。

我建议您熟悉 Sphinx markup ，因为它被广泛使用并且正在成为记录 Python 项目的事实上的标准，部分原因是优秀的 readthedocs.org服务。致paraphrase an example来自 Sphinx 文档中的 Python 片段:

def send_message(sender, recipient, message_body, priority=1) -> int:
   """
   Send a message to a recipient.

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring
   """

此标记支持 cross-referencing文件之间等等。请注意，Sphinx 文档使用(例如):py:attr:，而从源代码记录时您可以只使用 :attr:。

当然，还有其他工具可以记录 API。还有更经典的Doxygen它使用 \param commands但它们并不是专门为记录 Python 代码而设计的，比如 Sphinx。

请注意，有一个 similar question与 similar answer在这里……