介绍
Docstring（文档字符串）是 写在函数/类/模块开头的字符串注释，用于代码说明、IDE智能提示、自动生成文档、help()查看说明，区别于单行#注释。
定义位置
- 模块Docstring：
.py文件最顶端第一行字符串 - 类Docstring：
class X:下第一行 - 方法/函数Docstring：
def func():函数体内首行
主要：必须是第一个语句，否则不算文档字符串，变成普通字符串常量。
# 模块docstring
"""顶层模块文档：本模块实现XX工具"""
class User:
"""用户实体类：存储用户基础信息""" # 类docstring
def get_name(self, id: int) -> str:
"""根据用户ID获取用户名""" # 函数docstring
return ""
例子
1. 模块文档（文件开头）
"""
项目公共工具模块
================
功能：价格计算、日期格式化
Author: xxx
Version: 1.0
"""
import math
2. 类+实例方法/静态方法
class Goods:
"""商品业务类，统一管理商品计价"""
price = 100
@staticmethod
def count(num: int):
"""静态方法：批量计算原价总额"""
return Goods.price * num
3. 魔法方法 init
class User:
def __init__(self, uid: int, name: str):
"""
用户初始化构造函数
Args:
uid: 用户唯一编号
name: 用户昵称
"""
self.uid = uid
self.name = name
三种字符串写法都合法
# 单行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()读取：
print(add.__doc__)
help(add)
四大主流Docstring规范
行业4套标准，分别适配不同工具（pdoc/sphinx/pycharm）：
1. Google风格（最简洁、国内项目首选）
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风格（科学计算、数据分析项目）
字段最全，适合算法/数据科学，字段分段清晰。
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自动生成文档默认解析格式，开源项目老牌用法。
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规范约束
- PEP257：Docstring语法规范
- 单行doc：首尾引号同一行，末尾不加句号可选
- 多行doc：首行简述单独一行，空一行后详细说明，结尾引号单独一行
- PEP484：配合类型注解
: int / -> str，IDE联动doc识别参数类型
工具：基于Docstring自动生成文档
- Sphinx：搭配
sphinx.ext.napoleon解析Google/Numpy格式，生成HTML/PDF文档 - pdoc：一键生成网页文档，
pdoc xxx.py -o ./docs - pycharm/vscode：鼠标悬浮自动读取doc展示提示
- docstring-parser：代码读取doc字段解析成字典
自动生成Docstring插件
- VSCode：
autoDocstring一键根据函数生成模板（可选Google/Numpy格式） - PyCharm：内置自动生成doc模板（设置：Tools→Python Integrated Tools）
单行 vs 多行使用场景
- 单行Docstring：逻辑简单工具函数，一句话说明即可
- 多行Docstring：
- 参数≥2个
- 有返回值说明、异常抛出
- 接口函数、公共类（对外提供调用）