Question

除了#注释外，Python也支持可自动附加在对象上的文档，而且在运行时还可保存查看。从语法上来说，这类注释是写成字符串，放在模块文件、函数以及类语句的顶端，就在任何可执行程序代码前（#注释在其之前也没问题）。Python会自动封装这个字符串，也就是成为所谓的文档字符串，使其成为相应对象的__doc__属性。

用户定义的文档字符串

例如，考虑下面的文件docstrings.py。其文档字符串出现在文件开端以及其中的函数和类的开头。在这里，文件和函数多行注释使用的是三重引号块字符串，但是任何类型的字符串都能用。我们还没详细研究def或class语句，所以，除了它们顶端的字符串外，其他关于它们的内容都可以忽略。

这个文档协议的重点在于，注释会保存在__doc__属性中以供查看（文件导入之后）。因此，要显示这个模块以及其对象打算关联的文档字符串，我们只需要导入这个文件，简单的打印其__doc__属性（即Python储存文本的地方）即可：

注意：一般都需要明确说出要打印的文档字符串；否则你会得到嵌有换行字符的单个字符串。

你也可以把文档字符串附加到类的方法中（以后会谈），但是因为这些只是嵌套在类中的def语句，所以也不是什么特别的情况。要取出模块中类的方法函数的文档字符串，可以通过路径访问类：module.class.method.__doc__（参考第28章的方法的文档字符串的例子）。

文档字符串标准

文档字符串的文字应该有什么内容，并没有什么标准（不过有些公司有内部标准）。现在已经有各种标记语言和模板协议（例如，HTML或XML），但是，似乎没有在Python世界中流行起来。然而，坦率地讲，要说服程序员使用手动编写HTML为代码编写文档，那是不可能的！

通常来说，文档在程序员之间的优先级都偏低。而一般情况下，如果你看到文件中有任何注释，那都已经算是幸运了。不过，本书强烈建议你详细的为代码编写文档，这其实是写好代码的重要部分。这里的重点就是，目前文档字符串的结构没有标准。如果你想用，就别犹豫。

内置文档字符串

Python中的内置模块和对象都使用类似的技术，在dir返回的属性列表前后加上文档。例如，要查看内置模块的可读的说明时，可将其导入，并打印其__doc__字符串。

内置模块内的函数、类以及方法在其__doc__属性内也有附加的说明信息。

也可以通过文档字符串读取内置函数的说明。

可以用这种方式查看其文档字符串，从而得到内置工具的大量信息，但是你不必这样做：下一节的主题help函数会为你自动做这件事。