Python Docstring 文档注释详解（相当于Javadoc 文档注释）-马育民老师

# 介绍

Docstring（文档字符串）是 **写在函数/类/模块开头的字符串注释**，用于代码说明、IDE智能提示、自动生成文档、`help()`查看说明，区别于单行`#`注释。

# 定义位置

1. **模块Docstring**：`.py`文件最顶端第一行字符串
2. **类Docstring**：`class X:`下第一行
3. **方法/函数Docstring**：`def func():`函数体内首行

**主要：**必须是**第一个语句**，否则不算文档字符串，变成普通字符串常量。

```python
# 模块docstring
"""顶层模块文档：本模块实现XX工具"""

class User:
    """用户实体类：存储用户基础信息""" # 类docstring
    def get_name(self, id: int) -> str:
        """根据用户ID获取用户名""" # 函数docstring
        return ""
```

### 例子

##### 1. 模块文档（文件开头）
```python
"""
项目公共工具模块
================
功能：价格计算、日期格式化
Author: xxx
Version: 1.0
"""
import math
```

##### 2. 类+实例方法/静态方法
```python
class Goods:
    """商品业务类，统一管理商品计价"""
    price = 100

@staticmethod
    def count(num: int):
        """静态方法：批量计算原价总额"""
        return Goods.price * num
```

##### 3. 魔法方法 __init__
```python
class User:
    def __init__(self, uid: int, name: str):
        """
        用户初始化构造函数
        Args:
            uid: 用户唯一编号
            name: 用户昵称
        """
        self.uid = uid
        self.name = name
```

# 三种字符串写法都合法
```python
# 单行docstring：简短描述用
def add(a, b):
    """两数相加，返回求和结果"""
    return a + b

# 多行docstring：复杂说明用（三双引号推荐，PEP规范）
def sub(a, b):
    """
    减法运算
    入参：a被减数，b减数
    返回：a - b结果
    """
    return a - b

# 三单引号也支持，工程通用"""(双引号)"""
```

# 访问Docstring
Python自动存入对象`__doc__`属性，`help()`读取：
```python
print(add.__doc__)
help(add)
```

# 四大主流Docstring规范
行业4套标准，分别适配不同工具（pdoc/sphinx/pycharm）：

### 1. Google风格（最简洁、国内项目首选）

```python
def calc_price(num: int, discount: float = 1.0) -> float:
    """计算商品折后总价

Args:
        num: 商品购买数量，必须大于0
        discount: 折扣系数，默认1.0无折扣

Returns:
        float: 最终结算价格

Raises:
        ValueError: 当num<=0时抛出异常
    """
    if num <= 0:
        raise ValueError("数量不能小于等于0")
    return num * 100 * discount
```
**关键字段**：
- `Args`：入参说明，可标注类型
- `Returns`：返回值
- `Raises`：抛出异常
- `Examples`：代码示例
- `Note`：备注

### 2. NumPy风格（科学计算、数据分析项目）

字段最全，适合算法/数据科学，字段分段清晰。
```python
def calc_price(num: int, discount: float = 1.0) -> float:
    """
    计算商品折后总价

Parameters
    ----------
    num : int
        商品购买数量，必须大于0
    discount : float, default=1.0
        折扣系数，默认1.0无折扣

Returns
    -------
    float
        最终结算价格

Raises
    ------
    ValueError
        num<=0触发数值异常
    """
```

### 3. reStructuredText（Sphinx官方标准，老牌规范）
Sphinx自动生成文档默认解析格式，开源项目老牌用法。
```python
def calc_price(num: int, discount: float = 1.0) -> float:
    """计算商品折后总价

:param num: 商品购买数量，必须大于0
    :type num: int
    :param discount: 折扣系数，默认1.0无折扣
    :type discount: float, optional
    :return: 最终结算价格
    :rtype: float
    :raises ValueError: num<=0抛出异常
    """
```

### 4. Epytext（早期规范，现已淘汰，少用）

# PEP规范约束
1. **PEP257**：Docstring语法规范
    - 单行doc：首尾引号同一行，末尾不加句号可选
    - 多行doc：首行简述单独一行，空一行后详细说明，结尾引号单独一行
2. **PEP484**：配合类型注解 `: int / -> str`，IDE联动doc识别参数类型

# 工具：基于Docstring自动生成文档
1. **Sphinx**：搭配`sphinx.ext.napoleon`解析Google/Numpy格式，生成HTML/PDF文档
2. **pdoc**：一键生成网页文档，`pdoc xxx.py -o ./docs`
3. **pycharm/vscode**：鼠标悬浮自动读取doc展示提示
4. **docstring-parser**：代码读取doc字段解析成字典

# 自动生成Docstring插件
- VSCode：`autoDocstring` 一键根据函数生成模板（可选Google/Numpy格式）
- PyCharm：内置自动生成doc模板（设置：Tools→Python Integrated Tools）

# 单行 vs 多行使用场景
1. **单行Docstring**：逻辑简单工具函数，一句话说明即可
2. **多行Docstring**：
   - 参数≥2个
   - 有返回值说明、异常抛出
   - 接口函数、公共类（对外提供调用）

原文出处：http://malaoshi.top/show_1GW3Qo3NDN4B.html