"""Tests for foo.bar."""
3.8.3 函数和方法
下文所指的函数，包括函数，方法，生成器以及属性。
每个具有以下一项或多项特性的函数都必须有文档字符串：
公共 API 的一部分
文档字符串应该提供足够的信息，当别人编写代码调用该函数时，他不需要看一行代码，只要看文档字符串就可以了。
文档字符串应描述函数的调用语法和语义，但通常不描述其实现细节，除非这些细节与函数的使用方式相关。
例如，作为副作用会改变其参数的函数应在其文档字符串中注明这一点。否则，对于调用者不相关的函数实现的微妙但重要的细节，
最好将其表达为代码旁边的注释，而不是在函数的文档字符串中。
文档字符串应该是描述性的（ """Fetches rows from a Bigtable."""） 或者命令式的（ """Fetch rows from a Bigtable.""" ），
但是在一个文件中，风格应该保持一直。对于 @property 数据描述符的文档字符串应该使用与属性或函数参数的文档字符串相同的风格
（ """The Bigtable path.""" 而不是 """Returns the Bigtable path.""" ）。
重写基类中的方法时，用一个简单的文档字符串引导读者查看被覆盖方法的文档字符串，例如： """See base class."""
。这样做的好处是，无需重复基本方法中的文档字符串信息。但是，如果重写方法的行为发生了改变，或者需要提供详细信息（例如：记录额外副作用），那么重写方法至少需要通过文档字符串来描述这些差异。
关于函数的几个方面应该在特定的小节中进行描述记录。这几个方面如下文所述，每节应该以一个标题行开始，标题行以冒号结尾。除标题行外，小节的其他内容应被缩进两个或四个空格（在文件内保持一致）。如果函数的名称和签名具有足够的信息，可以使用单行文档字符串进行适当描述，那就可以省略这些部分。
Args:
列出每个参数的名字，在名字后使用一个冒号和一个空格，分隔对该参数的描述。如果描述太长超过了单行80字符，使用2或者4个空格的悬挂缩进（与文件其他部分保持一致）。描述应该包括所需的类型和含义。如果一个函数接受 *foo
（可变长度参数列表）或者 **bar（任意关键字参数），应该详细列出 *foo 和 **bar 。
Returns:（或者 Yields: 用于生成器）
返回值的语义应该被描述清楚，包括类型注释所不能提供的任何类型信息。
如果函数只返回 None，则不需要此部分。如果文档字符串以 Returns 或 Yields 开头
（例如 """Returns row from Bigtable as a tuple of strings."""），并且开头的句子足以描述返回值，则可以省略此部分。
不要模仿像 NumPy风格，该风格通常将元组返回值记录为多个带有单独名称的返回值（从不提到元组）。
相反，应将此类返回值描述为：Returns: A tuple (mat_a, mat_b), where mat_a is …, and …。
文档字符串中的辅助名称不一定需要与函数体中使用的任何内部名称相对应（因为它们不是 API 的一部分）。
Raises:
列出与接口有关的所有异常，然后给出说明。使用类似的异常名称 + 冒号 + 空格或换行符，并按 Args： 中所述悬挂缩进样式。如果违反了文档字符串中指定的
API，则不应该记录引发的异常（因为这会使违反 API 的行为成为 API 的一部分）。
