Here are some conventions about the content and formatting of documentation strings.

下面是文档字符串的内容和形式方面的惯例。

The first line should always be a short, concise summary of the object’s purpose. For brevity, it should not explicitly state the object’s name or type, since these are available by other means (except if the name happens to be a verb describing a function’s operation). This line should begin with a capital letter and end with a period.

第一行应该是对对象目的的简短总述。简单的说，它不应该显式地声明对象的名称或类型，因为它们可以通过其他方法获得（除非名称产生关于函数行为的描述）。这一行应该以大写字母开头并以句号结尾。

If there are more lines in the documentation string, the second line should be blank, visually separating the summary from the rest of the description. The following lines should be one or more paragraphs describing the object’s calling conventions, its side effects, etc.

如果文档字符有很多行，那么第二行应该为空行，这样在视角上可以区分总述和剩余的描述。以下几行应该是一个或多个段落，描述对象的调用约定及其副作用。

The Python parser does not strip indentation from multi-line string literals in Python, so tools that process documentation have to strip indentation if desired. This is done using the following convention. The first non-blank line after the first line of the string determines the amount of indentation for the entire documentation string. (We can’t use the first line since it is generally adjacent to the string’s opening quotes so its indentation is not apparent in the string literal.) Whitespace “equivalent” to this indentation is then stripped from the start of all lines of the string. Lines that are indented less should not occur, but if they occur all their leading whitespace should be stripped. Equivalence of whitespace should be tested after expansion of tabs (to 8 spaces, normally).

Python解析器不会从Python中的多行字符串文本中去除缩进，因此如果需要，处理文档的工具必须去除缩进。关于缩进使用下面的约定可以完成。第一行之后的第一个非空行的行决定了文档字符内容的多个缩进。（我们不能使用第一行，因为它通常与字符串的开始引号相邻，所以它的缩进在字符串文本中不明显。）然后从字符串的所有行开始删除与此缩进“等效”的空白。缩进少的行不应该出现，但是如果出现，则应该删除所有的前导空格。空格的等效性应在展开制表符后进行测试（通常，有8个位置）

Here is an example of a multi-line docstring:

下面是多行文档字符的例子：

>>>

>>> def my_function():

...     """Do nothing, but document it.

......     No, really, it doesn't do anything.

...     """

...     pass

...

>>> print(my_function.__doc__)

Do nothing, but document it.

    No, really, it doesn't do anything.

4.7.7. Function Annotations函数注释

Function annotations are completely optional metadata information about the types used by user-defined functions (see PEP 3107 and PEP 484 for more information).

函数注释是关于用户定义函数使用的类型的完全可选的元数据信息

Annotations are stored in the __annotations__ attribute of the function as a dictionary and have no effect on any other part of the function. Parameter annotations are defined by a colon after the parameter name, followed by an expression evaluating to the value of the annotation. Return annotations are defined by a literal ->, followed by an expression, between the parameter list and the colon denoting the end of the def statement. The following example has a positional argument, a keyword argument, and the return value annotated:

注释作为字典存储在函数__annotations__属性中，且对函数其他部分没有影响。在参数名后使用冒号来定义参数注释，后面跟着对于注释解释的表达式。在参数列表和冒号表示的def语句结尾之间，返回注释通过定义的->符号，后面跟一个表达式。下面的例子有一个位置参数，一个关键字参数，和一个带注释的返回值。

>>>

>>> def f(ham: str, eggs: str = 'eggs') -> str:

...     print("Annotations:", f.__annotations__)

...     print("Arguments:", ham, eggs)

...     return ham + ' and ' + eggs

...

>>> f('spam')

Annotations: {'ham': <class 'str'>, 'return': <class 'str'>, 'eggs': <class 'str'>}

Arguments: spam eggs'spam and eggs'

---

读官网文档是程序员最重要的必备技能!

4.7.6. Documentation Strings&4.7.7. Function Annotations函数注释