journal of python(3) －－dive into python

You can document a Python function by giving it a doc string.

你可以通过给函数一个文档化字符串（？？？函数注释）来文档化一个函数

Defining the buildConnectionString Function's doc string定义buildConnectionString函数的文档化字符串

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

    Returns string."""

Triple quotes signify a multi-line string. Everything between the start and end quotes is part of a single string, including carriage returns and other quote characters. You can use them anywhere, but you'll see them most often used when defining a doc string三元双引号确定了一个多行的字符串。在两个三元双引号开始和结束部分所包含的所有内容都是简单字符串，包括回车和其它字符。你在其它地方也可能看到他们，但是在大部分情况下这些字符都是用来定义文档化字符串。

Triple quotes are also an easy way to define a string with both single and double quotes, like qq/.../ in Perl.
就像在Perl中，三元字符串使用简单字符串和双引号可以很轻松的定义一个字符串，比如 qq/.../

Everything between the triple quotes is the function's doc string, which documents what the function does. A doc string, if it exists, must be the first thing defined in a function (that is, the first thing after the colon). You don't technically need to give your function a doc string, but you always should. I know you've heard this in every programming class you've ever taken, but Python gives you an added incentive: the doc string is available at runtime as an attribute of the function.

在三元字符串中的所有字符串都是函数的文档化字符串，它描述了函数是用来做什么的。文档化字符串，如果存在，那么它必须是函数定义后所作的第一件事，换句话说，它必须紧跟在函数定义的冒号后面，如果有的话。从技术的角度，你不必给函数一个文档化字符串，但是你应该定义一个。我知道，在你所参加的所有课程中，你都被告知要添加文档化字符串，但是Python给你了一个额外的理由：文档化字符串作为函数的属性在运行时是可用的。

Many Python IDEs use the doc string to provide context-sensitive documentation, so that when you type a function name, its doc string appears as a tooltip. This can be incredibly helpful, but it's only as good as the doc strings you write.
许多PythonIDE 通过文档化字符串来提供上下文敏感的文档，这样当你输入一个函数名得时候，函数的文档化字符串就可以作为一个提示出现。这是十分有用的，你自己写的文档化字符处也是同样有用的。