用途:在采用 Google 风格(由 Sphinx Napoleon 编译)的 Python 项目中,帮助编写、编辑和审查 docstring,让文档同时面向阅读提示信息的开发者和渲染 API 文档的 Sphinx。
主要能力与规范:
- 分节顺序为 Args: → Returns:/Yields: → Raises: → Attributes:/Examples:/Note:;条目写作 name (type): description,续行多缩进一级;可变参数保留星号(*args、**kwargs)。
- 摘要行紧接三引号后一行,以 . ? ! 结尾,其余内容前留空行;说明调用者能获得什么,避免“This function ...”式表述。同一文件内描述式与祈使式语气需保持一致。
- Google 仅在参数缺少注解时要求 (type) 标记,但资料建议仍保留,以保持 docstring 自包含。
- 支持 :class:、:meth:、:func:、:attr:、:exc:、:data: 等 Sphinx 角色及 ~ 前缀;字面值使用双反引号。
- Raises: 只记录与调用者接口相关且说明触发条件的异常;不记录因调用者违反约定而抛出的异常;协议接口仅在抛出属于契约时添加。
- 类属性、属性、生成器、类型别名、常量、TypedDict、@overload/Protocol 桩各有写法(见 references/constructs.md),原则是在调用者接触的层级记录契约。
- 默认仅写摘要行,仅在有非显而易见行为、副作用、不变量或“为什么”时补充 1–3 句正文。不重复类型,类型由 (type) 承载。
- 格式:分节正文在关键字下缩进 4 空格,续行 8;约 88 列换行;摘要必须保持单物理行。
适用场景:使用 Google 风格 docstring 并配合 Sphinx Napoleon 的 Python 项目。
限制与反模式:避免用文字重述类型、空泛或无信息的分节、同一项目混用 Args: 与 Parameters;属性不应写成“Returns the path.”而应像属性一样描述其值。相关技能包括 python-rest-docstrings、readable-code 和 altitude-docs。安装命令与其他用法细节暂未提供。