Python文档，高级Py注释

之前看过很多开源Python项目，都有注意到它们各个方法或类下方都有一个由三引号'''或"""包裹的字符串。在刚开始学习Python时我了解到三引号的字符串可以是多字符串，也可以是注释，但随着我对Python语言的深入学习，发现这类字符串并不是简简单单的注释。这篇文章就来详细汇总一下Python的三引号字符串是如何作为文档使用的。

基础用法

Python文档由三引号定义，通常在声明类名的下一行即class xxx:的下一行和声明函数名的下一行即def f(xxx):的下一行以及模块的最顶部出现。Python文档可由该类或该函数的__doc__属性获取。

下面以一个类和一个方法举例。下面的例子中，类Person具有一个文档，成员方法__init__有一个文档，方法show_doc也有一个文档，随后输出它们的文档属性就可以输出它们的文档了。

"""
此模块为演示模块。
"""


class Person:
    """
    Person类，用于存储人员信息。
    """

    def __init__(self, name=None, age=None):
        """
        初始化方法。
        :param name: 名字
        :param age: 年龄
        """
        self.name = name
        self.age = age


def show_doc(obj):
    """
    打印对象的文档属性。
    :param obj: 要打印文档的对象
    :return: 无返回值
    """
    print(obj.__doc__)

import __main__
print(Person.__doc__)
print(Person.__init__.__doc__)
print(show_doc.__doc__)
print(__main__.__doc__)

运行结果如下。

运行结果

注：对自身模块进行引用并获取其中的属性需要导入__main__模块。

合理利用文档可以增加代码的可读性，能够使其他人更快更容易理解代码，在合作中编写一个良好的文档是一个良好的编程习惯。PyCharm就将文档利用得非常好，它可以自动获取文档字符串，并在title中显示出来。

当将指针悬浮于类名上时PyCharm给出的提示

高级用法

除此之外，Python的文档字符串还有一些特殊的格式，以更加直观地描述对应的内容。

上方文档中:param name: 名字就是用来描述函数的参数name的。

使用:param描述函数参数

下面只介绍一些比较常用的文档字符串的用于描述对应内容的特殊语法结构。

• :param name: description：用于描述函数或方法的参数，其中name是参数的名称，description是对参数的描述。
• :param name: description, optional：用于描述可选的参数。
• :param name: description, default value：用于描述带有默认值的参数。
• :param name: description, optional, default value：用于描述既是可选的又有默认值的参数。
• :type name: type：用于指定参数的类型，其中name是参数的名称，type是参数的数据类型。
• :return: description：用于描述函数或方法的返回值，其中description是对返回值的描述。
• :rtype: type：用于指定返回值的类型，其中type是返回值的数据类型。
• :keyword arg: description：用于描述函数或方法的关键字参数，其中arg是关键字参数的名称，description是对关键字参数的描述。
• :raises exception_type: description：用于描述函数或方法可能引发的异常类型和异常描述。
• :Example:：用于给出示例代码。
• :Examples:：用于给出多个示例代码。
• :Warning:：用于给出警告信息。
• :Note:：用于给出特殊注意事项。
• :See Also:：用于指向相关的函数、类或模块。
• :todo: todo_item：用于标记需要完成的任务或待办事项。
• :bug: bug_description：用于标记已知的 bug 或缺陷。

下面给出一个较为详细的例子，看看这些文档在PyCharm中都是如何描述的。

class Person:
    """
    人员类，用于表示一个人类个体。
    Usage::
        >>> person = Person('张三', 18)
        >>> person.get()
        张三今年18岁了。
    """

    def __init__(self, name: str = None, age: int = 0):
        """
        构造函数，初始化人类时调用。
        :param name: 名字
        :type name: str
        :param age: 年龄
        :type age: int
        :raises ValueError: 在年龄小于0时引发此异常。
        """
        if age < 0:
            raise ValueError(f'年龄小于0：{age}')
        self.name = name
        self.age = age

    def get(self) -> str:
        """
        获取个人信息。
        :return: 表示返回的那个人的信息。
        :rtype: str
        """
        return f'{self.name}今年{self.age}岁了。'

person = Person('张三', 18)
print(person.get())

悬浮在Person类上时PyCharm的提示

悬浮在Person类的__init__方法上时PyCharm的提示

悬浮在Person类的get方法上时PyCharm的提示

所以小伙伴们养成写文档、写注释的好习惯吧。