如何使用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
文档字符串只在交互环境中有用，例如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
你不能用文档字符串做这种事情。
在类型提示回答(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
示例:https://pypi.org/project/autocommand/
由于文档字符串是自由形式的，因此它实际上取决于您使用什么来解析代码以生成API文档。
我建议熟悉Sphinx标记，因为它被广泛使用，并且正在成为记录Python项目的事实上的标准，部分原因是出色的readthedocs.org服务。将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
"""
该标记支持文档之间的交叉引用。请注意，Sphinx文档使用(例如):py:attr:，而当从源代码中进行记录时，您可以只使用:attr:。
当然，还有其他工具可以记录api。还有更经典的Doxygen，它使用\param命令，但它们不像Sphinx那样专门用于记录Python代码。
注意，这里有一个类似的问题和类似的答案……
