01A15.Learning Python 5th-文档

本笔记是基于《Python学习手册-原书第五版》第十五章 文档

文档是一个与工具相关的概念，文档涉及了Python的语法模型，文档是Python工具集的学习资源。

# 注释

注释使我们为代码编写文档最基本的方式，Python会忽略#之后的所有文字。

注释只能从源代码文件中看到。

dir函数

内置的dir函数是抓取对象内所有可用属性列表的一种简单方式。 

如果不向dir函数传入参数，则可以列出调用者作用域内的变量。也可以传入任何有属性的独享，包括被导入的模块、内置类型和数据类型的名字。

在Python的命名中，双下划线开头通常意味着与解释器相关，单下划线开头通常意味着非正式的私有属性实现。

__doc__文档字符串

Python支持可自动附加在对象上的文档，从而可以再运行时查看。

从语法上讲，这种注释被写成字符串，放在模块文件、函数以及类语句的顶部，位于任何可执行代码前。这些字符串被称为文档字符串，在Python中会自动装载文档字符串的文本，使其称为__doc__属性。

要去除模块中类的方法的文档字符串，可以通过点号路径来访问——module.class.method.__doc__

详细地为代码编写文档，是写好代码的重要的步骤。

# 先创建一个名为test01.py的测试文件
"""
文档字符串位置001
"""
def aaa(x):
    """
    文档字符串位置002
    """
    pass

class bbb:
    """
    文档字符串位置003
    """
    pass

# 在另一个源代码中
import test001

print(test001.__doc__)
print(test001.aaa.__doc__)
print(test001.bbb.__doc__)
# 的运行结果为
文档字符串位置001


    文档字符串位置002
    

    文档字符串位置003

PyDoc

PyDoc工具是一段Python程序，用于提取文档字符串及相关的结构化信息，并将它们排版城外观精美的多种报告。

help函数。当你调用help时，并不一定要导入sys模块；但是如果想用help来获取sys的文档信息时，就需要导入sys；help希望你传入一个对象的引用值。可以对模块，内置函数，方法以及类型使用help函数。