问题：如何用参数记录方法？
如何使用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
回答 0
根据我的经验，numpy的文档字符串公约（PEP257超集）是最广泛的传播遵循惯例，它们也通过工具，如支持的狮身人面像。
一个例子：
Parameters
----------
x : type
Description of parameter `x`.回答 1
由于文档字符串是自由格式的，所以它实际上取决于您用来解析代码以生成API文档的内容。
我建议您熟悉Sphinx标记，因为它已被广泛使用并且已成为记录Python项目的实际标准，部分原因在于出色的readthedocs.org服务。要将Sphinx文档中的示例解释为Python代码段，请执行以下操作：
def send_message(sender, recipient, message_body, priority=1):
'''
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
'''该标记支持文档之间以及其他之间的交叉引用。请注意，Sphinx文档使用（例如），:py:attr:而您只能:attr:在从源代码进行文档记录时使用。
自然，还有其他工具可以记录API。有更经典的Doxygen使用\param 命令，但是这些命令并非像Sphinx一样专门用于记录Python代码。
回答 2
约定：
工具：
更新：从Python 3.5开始，您可以使用类型提示，这是一种紧凑的，机器可读的语法：
from typing import Dict, Union
def foo(i: int, d: Dict[str, Union[str, int]]) -> int:
"""
Explanation: this function takes two arguments: `i` and `d`.
`i` is annotated simply as `int`. `d` is a dictionary with `str` keys
and values that can be either `str` or `int`.
The return type is `int`.
"""这种语法的主要优点是它是由语言定义的，而且语言明确，因此PyCharm之类的工具可以轻松地从中受益。
回答 3
python doc字符串是自由格式的，您可以按自己喜欢的任何方式对其进行记录。
例子：
def mymethod(self, foo, bars):
"""
Does neat stuff!
Parameters:
foo - a foo of type FooType to bar with.
bars - The list of bars
"""现在，有一些约定，但是python没有强制执行任何约定。有些项目有自己的约定。一些使用文档字符串的工具也遵循特定的约定。
回答 4
如果您打算使用Sphinx来记录您的代码，它可以使用其“签名”功能为您的参数生成格式精美的HTML文档。 http://sphinx-doc.org/domains.html#signatures
回答 5
正如此处其他答案所指出的那样，主流可能是Sphinx方法，以便您以后可以使用Sphinx生成那些精美的文档。
话虽如此，我个人有时还是采用内联评论风格。
def complex( # Form a complex number
real=0.0, # the real part (default 0.0)
imag=0.0 # the imaginary part (default 0.0)
): # Returns a complex number.
"""Form a complex number.
I may still use the mainstream docstring notation,
if I foresee a need to use some other tools
to generate an HTML online doc later
"""
if imag == 0.0 and real == 0.0:
return complex_zero
other_code()这里还有一个示例，内联记录了一些小细节：
def foo( # Note that how I use the parenthesis rather than backslash "\"
# to natually break the function definition into multiple lines.
a_very_long_parameter_name,
# The "inline" text does not really have to be at same line,
# when your parameter name is very long.
# Besides, you can use this way to have multiple lines doc too.
# The one extra level indentation here natually matches the
# original Python indentation style.
#
# This parameter represents blah blah
# blah blah
# blah blah
param_b, # Some description about parameter B.
# Some more description about parameter B.
# As you probably noticed, the vertical alignment of pound sign
# is less a concern IMHO, as long as your docs are intuitively
# readable.
last_param, # As a side note, you can use an optional comma for
# your last parameter, as you can do in multi-line list
# or dict declaration.
): # So this ending parenthesis occupying its own line provides a
# perfect chance to use inline doc to document the return value,
# despite of its unhappy face appearance. :)
pass好处（如@ mark-horvath在另一条评论中已经指出的）是：
- 最重要的是，参数及其文档始终保持在一起，这带来了以下好处：
- 更少的输入（无需重复变量名）
- 更改/删除变量时更容易维护。重命名某些参数后，将永远不会有任何孤立参数doc段落。
- 更容易找到遗漏的评论。
现在，有些人可能认为这种样式看起来“丑陋”。但是我会说“丑陋”是一个主观的词。更为中性的说法是，这种风格不是主流，因此您看起来不太熟悉，因此不太舒适。同样，“舒适”也是一个主观词。但是关键是，上述所有好处都是客观的。如果遵循标准方法，则无法实现它们。
希望在将来的某一天，将有一个文档生成器工具也可以使用这种内联样式。这将推动采用。
PS：这个答案来自我自己的偏爱，即在我认为合适时使用内联注释。我也使用相同的内联样式来记录字典。
回答 6
建立在类型提示答案（https://stackoverflow.com/a/9195565/2418922）的基础上，该答案提供了一种更好的结构化方式来记录参数类型，还存在一种结构化方式来记录参数的类型和描述：
def copy_net(
infile: (str, 'The name of the file to send'),
host: (str, 'The host to send the file to'),
port: (int, 'The port to connect to')):
pass回答 7
文档字符串仅在交互式环境（例如Python shell）中有用。在记录将不会交互使用的对象（例如内部对象，框架回调）时，您最好使用常规注释。这是我用来将缩进的注释挂在项目上的样式，每个项目都在自己的行上，因此您知道该注释适用于：
def Recomputate \
(
TheRotaryGyrator,
# the rotary gyrator to operate on
Computrons,
# the computrons to perform the recomputation with
Forthwith,
# whether to recomputate forthwith or at one's leisure
) :
# recomputates the specified rotary gyrator with
# the desired computrons.
...
#end Recomputate您无法使用docstrings做这种事情。
