Python 文档注释的写法

1. 基本说明

文档注释写在 函数, 类, 模块等封装中.

• 按照行数分: 单行, 多行

• 按照风格分(都是多行): Google 风格, NumPy/SciPy 风格

注释写在函数, 类的内部开头的位置. 使用三引号来引用. 注释内有换行的为多行注释.

def 函数名(参数):
    """
    描述函数功能
    参数:
    	参数(类型): 参数说明
    	...
    返回:
    	类型: 返回类型说明
    异常:
    	异常类型: 异常说明
    """
    # 函数体

2. Google 风格

def func_name(arg1, arg2):
    """函数功能说明
    
    Args:
    	arg1 (类型): 参数说明
    	arg2 (类型): 参数说明
    
    Returns:
    	返回值类型, 与功能, 算法说明
    
    Raises:
    	异常类型: 说明
    """
    # 函数体

3. NumPy/SciPy 风格

def func_name(arg1, arg2):
    """
    函数功能说明
    
    Parameters
    ----------
    arg1: 类型
          参数说明
    arg2: 类型
          参数说明
    
    Returns
    -------
    返回值类型
          返回值说明
    
    Examples
    --------
    >>> func_name(123, 456)
    预期结果
    ...
    """
    # 函数体

代码中, 可以使用 函数名.__doc__ 或 help(函数名) 来获得注释内容.