文档字符串

文档字符串
  Python的文档字符串,英文全称是documentation strings,简称docstrings。
  文档字符串提供了方便的方法,将文档附加到Python的对象上,这里的对象包括:模块module、函数function、类class和方法method。
  文档字符串需要在Python对象中的第一行开始。使用三个双引号或者三个单引号作为文档字符串内容的开始和结尾。
  文档字符串在形式上与注释相同,但两者有明显的不同:在程序运行过程中,注释被忽略了,就像完全不存在注释一样;而对于文档字符串来说,程序可以获取文档字符串的内容。
    每个Python的对象都应该有对应的文档字符串。
    可以通过__doc__属性获取文档字符串的内容。
    对于文档字符串,有一些约定俗成的规则:
        1.每个Python的对象都应该有对应的文档字符串,这里所说的对象包括:模块module、函数function、类class和方法method;
        2.文档字符串用来描述对象的功能,而不像注释那样用来描述如何实现;
        3.文档字符串的内容通常包括第一行是概要、第二行是个空行,剩余是详细的描述。
  下面是一个使用文档字符串的例子:
  文件student.py的内容:
# -*- coding: utf-8 -*-
# filename: student.py

'''
    这是模块的文档字符串
    
    定义了一个学生类,包含三个方法。
'''

class Student():
    '''
    这是类Student的文档字符串
    
    包含三个方法
    '''
    def __new__(cls, name, scope):
        '''这是方法__new__()的文档字符串'''
        
        print('Create and return a instance in __new__().')
        instance = super().__new__(cls) # 创建了类Student的实例
        
        return instance                 # 返回创建的实例
        
    def __init__(self, name, scope):    # __new__()创建并返回的实例通过形参self传递给__init__()
        '''这是方法__init__()的文档字符串'''
        
        print('Initialize instance in __init__().')
        self.name = name
        self.scope = scope
        
    def printInfo(self):                # 通过参数self接收实例
        '''这是方法printInfo()的文档字符串'''
        
        print('name: ', self.name)
        print('scope: ', self.scope)
        
# student = Student('Lucy', 85)         # 创建Student实例时,会自动调用方法__new__()和__init__()
# student.printInfo()

文件docstrings.py的内容:

import student

print(student.__doc__)
print(student.Student.__doc__)
print(student.Student.__new__.__doc__)
print(student.Student.__init__.__doc__)
print(student.Student.printInfo.__doc__)

上面的程序输出:

    这是模块的文档字符串

    定义了一个学生类,包含三个方


    这是类Student的文档字符串

    包含三个方法

这是方法__new__()的文档字符串
这是方法__init__()的文档字符串
这是方法printInfo()的文档字符串