1.3. Documenting functions

1.3. 文档化函数

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

例 1.4. 定义 buildConnectionString 函数的文档字符串

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

    Returns string."""

三重引号的引用表示一个多行字符串。所有在开始与结束引号间的东西都被视为单个字符串的一部分，包括硬回车和其它的引号字符。可以在任何地方使用它们，但是你可以看到在定义文档字符串的时候它们被经常使用到。


	三重引号也是一种定义即含有单引号又含有双引号的字符串的简单方法，就象Perl中的 `qq/.../` 。

任何在这个三重引号中的东西都是这个函数的文档字符串，它们用来说明函数可以做什么。如果存在文档字符串，它必须要在函数中的被首先定义(也就是说在冒号后面被定义)。在技术上不必须给出函数的文档字符串，但是你应该经常这样做。我相信在你所参加过的每一节编程课上已经听到过这一点，但是Python带给你一些额外的动机：文档字符串在运行时可作为函数的属性。


	许多Python IDE使用文档字符串来提供上下文相关提示，这样当你敲入一个函数名，它的文档字符串将显示为提示框。这一点相当的有用，但是取绝于你写的文档字符串的好坏了。

进一步阅读

Python Style Guide 讨论了如何写出好的文档字符串。
Python Tutorial 讨论了对于文档字符串中的空白的习惯。