使用 docstrings 编写文档

一个文档字符串是一个多行注释用于记录模块，类，函数和方法。它必须是它描述的组件的第一个声明。

def hello(name):
    """Greet someone.

    Print a greeting ("Hello") for the person with the given name.
    """

    print("Hello "+name)

class Greeter:
    """An object used to greet people.

    It contains multiple greeting functions for several languages
    and times of the  day.
    """

docstring 的值可以在程序中访问， 并且 - 例如 - 由 help 命令使用。

语法约定

PEP 257

PEP 257 定义了文档字符串注释的语法标准。它基本上允许两种类型：

• 单行 Docstrings：

根据 PEP 257，它们应该用于简短的功能。一切都放在一行，例如：

def hello():
    """Say hello to your friends."""
    print("Hello my friends!")

文档字符串应以句号结尾，动词应以命令形式结束。

• 多行文档字符串：

多行文档字符串应该用于更长，更复杂的函数，模块或类。

def hello(name, language="en"):
    """Say hello to a person.

    Arguments:
    name: the name of the person
    language: the language in which the person should be greeted
    """

    print(greeting[language]+" "+name)

它们以简短的摘要（相当于单行文档字符串的内容）开头，它可以与引号位于同一行或下一行，提供其他详细信息和列表参数以及返回值。

注意 PEP 257 定义了应该在 docstring 中给出的信息 ，它没有定义应该给出的格式。这就是其他方和文档解析工具为文档指定自己的标准的原因，其中一些列在下面和这个问题中 。

狮身人面像

Sphinx 是一个基于 docstrings 为 Python 项目生成基于 HTML 的文档的工具。它使用的标记语言是 reStructuredText 。他们定义了自己的文档标准，pythonhosted.org 主持了对它们的非常好的描述 。例如， pycharm IDE使用 Sphinx 格式。

使用 Sphinx / reStructuredText 格式可以像这样记录一个函数：

def hello(name, language="en"):
    """Say hello to a person.

    :param name: the name of the person
    :type name: str
    :param language: the language in which the person should be greeted
    :type language: str
    :return: a number
    :rtype: int
    """

    print(greeting[language]+" "+name)
    return 4

Google Python 样式指南

Google 发布了 Google Python 样式指南 ，该指南定义了 Python 的编码约定，包括文档注释。与 Sphinx / reST 相比，许多人说根据 Google 指南的文档更易于人类阅读。

上面提到的 pythonhosted.org 页面还提供了一些根据 Google Style Guide 提供的良好文档示例。

使用 Napoleon 插件，Sphinx 还可以解析符合 Google Style Guide 标准的文档。

使用 Google 样式指南格式可以将此功能记录为：

def hello(name, language="en"):
    """Say hello to a person.

    Args:
        name: the name of the person as string
        language: the language code string

    Returns:
        A number.
    """

    print(greeting[language]+" "+name)
    return 4