Python文档字符串是自由形式的，你可以用任何你喜欢的方式来记录它。

例子:

def mymethod(self, foo, bars):
    """
    Does neat stuff!
    Parameters:
      foo - a foo of type FooType to bar with.
      bars - The list of bars
    """

现在，有一些约定，但是python没有强制执行它们。有些项目有自己的约定。一些处理文档字符串的工具也遵循特定的约定。

Python文档字符串是自由形式的，你可以用任何你喜欢的方式来记录它。

例子:

def mymethod(self, foo, bars):
    """
    Does neat stuff!
    Parameters:
      foo - a foo of type FooType to bar with.
      bars - The list of bars
    """

现在，有一些约定，但是python没有强制执行它们。有些项目有自己的约定。一些处理文档字符串的工具也遵循特定的约定。

在类型提示回答(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/

根据我的经验，numpy文档字符串约定(PEP257超集)是最广泛遵循的约定，Sphinx等工具也支持这些约定。

一个例子:

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

如果您计划使用Sphinx来记录您的代码，那么它可以通过“签名”功能为您的参数生成格式良好的HTML文档。http://sphinx-doc.org/domains.html#signatures

约定:

PEP 257文档字符串约定 PEP 287 reStructuredText文档字符串格式

工具:

Epydoc:为Python自动生成API文档 autodoc -包括文档字符串中的文档 PyCharm对文档字符串有一些很好的支持

更新:从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这样的工具可以很容易地利用它。