Python基础教程 给函数编写文档

6.3.1 给函数编写文档

要给函数编写文档，以确保其他人能够理解，可添加注释（以#打头的内容）。还有另一种编写注释的方式，就是添加独立的字符串。在有些地方，如def语句后面（以及模块和类的开头，这将在第7章和第10章详细介绍），添加这样的字符串很有用。放在函数开头的字符串称为文档字符串（docstring），将作为函数的一部分存储起来。下面的代码演示了如何给函数添加文档字符串：

def square(x):

'Calculates the square of the number x.'

return x * x

可以像下面这样访问文档字符串：

>>> square.__doc__

'Calculates the square of the number x.'

注意__doc__是函数的一个属性。属性将在第7章详细介绍。属性名中的双下划线表示这是一

个特殊的属性。特殊（“魔法”）属性将在第9章讨论。

特殊的内置函数help很有用。在交互式解释器中，可使用它获取有关函数的信息，其中包含函数的文档字符串。

>>> help(square)

Help on function square in module __main__:

square(x)

Calculates the square of the number x.

在第10章，你还会遇到函数help。