SuperAPI AI 工具集

python-google-docstrings

编程与开发

查看项目

更新于 10-16 01:19

技能介绍

用途:在采用 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。安装命令与其他用法细节暂未提供。