Question

2.3. 文档化函数

可以通过给出一个 doc string (文档字符串) 文档化一个 Python 函数。

例 2.2. 定义 buildConnectionString 函数的 doc string

def buildConnectionString(params):
    """Build a connection string from a dictionary of parameters.
    Returns string."""

三重引号表示一个多行字符串。在开始与结束引号间的所有东西都被视为单个字符串的一部分, 包括硬回车和其它的引号字符。您可以在任何地方使用它们, 但是您可能会发现它们经常被用于定义 doc string 的情况。

	三重引号也是一种定义既包含单引号又包含双引号的字符串的简单方法, 就像 Perl 中的 qq/.../ 。

在三重引号中的任何东西都是这个函数的 doc string, 它们用来说明函数可以做什么。 如果存在 doc string, 它必须是一个函数要定义的第一个内容( 也就是说, 在冒号后面的第一个内容 )。 在技术上不要求给出函数的 doc string, 但是您应该这样做。我相信在您上过的每一种编程课上都听到过这一点, 但是 Python 带给您一些额外的动机： doc string 在运行时可作为函数的属性。

	许多 Python IDE 使用 doc string 来提供上下文敏感文档信息, 所以当键入一个函数名时, 它的 doc string 显示为一个工具提示。这一点可以说非常有用, 但是它的好坏取决于您书写的 doc string 的好坏。

进一步阅读

• PEP 257 定义了 doc string 规范。
• Python Style Guide 讨论了如何编写一个好的 doc string。
• Python Tutorial 讨论了在 doc string 中如何使用空白。