python教程（八）函数文档和标注

文档字符串

以下是有关文档字符串的内容和格式的一些约定。第一行应该是对象目的的简要概述。为简洁起见，它不应显式声明对象的名称或类型，因为这些可通过其他方式获得（除非名称恰好是描述函数操作的动词）。这一行应以大写字母开头，以句点结尾。

 

如果文档字符串中有更多行，则第二行应为空白，从而在视觉上将摘要与其余描述分开。后面几行应该是一个或多个段落，描述对象的调用约定，它的副作用等。

 

Python解析器不会从Python中删除多行字符串文字的缩进，因此处理文档的工具必须在需要时删除缩进。这是使用以下约定完成的。文档字符串第一行 之后 的第一个非空行确定整个文档字符串的缩进量。（我们不能使用第一行，因为它通常与字符串的开头引号相邻，因此它的缩进在字符串文字中不明显。）然后从字符串的所有行的开头剥离与该缩进 "等效" 的空格。 缩进的行不应该出现，但是如果它们出现，则应该剥离它们的所有前导空格。应在扩展标签后测试空白的等效性（通常为8个空格）。

 

函数标注

函数标注 是关于用户自定义函数中使用的类型的完全可选元数据信息（有关详情请参阅 PEP 3107 和 PEP 484 ）。

函数标注 以字典的形式存放在函数的 __annotations__ 属性中，并且不会影响函数的任何其他部分。 形参标注的定义方式是在形参名称后加上冒号，后面跟一个表达式，该表达式会被求值为标注的值。 返回值标注的定义方式是加上一个组合符号   ->，后面跟一个表达式，该标注位于形参列表和表示 def 语句结束的冒号之间。 下面的示例有一个位置参数，一个关键字参数以及返回值带有相应标注: