咨询Numpydoc风格下返回类实例的文档写法是否合规
2026-5-14
关于Numpydoc风格中返回类实例的文档规范疑问
我正在遵循Numpydoc风格指南编写代码文档，但未找到返回类实例的规范。以下是我编写的文档示例：
""" 在meilisearch API中创建索引。若未传入参数`uid`，将由meilisearch自动生成；若未传入参数`name`，则会触发错误。 Parameters ---------- name: str 索引的名称 uid: str, optional 索引的唯一标识符 Raises ------ HTTPError 当未传入name参数时触发。 HTTPError 当出现meilisearch官方文档中提及的其他错误时触发。 Returns ------- index 包含新建索引信息的Index类实例 """如您所见，我在Returns部分标注了返回Index类实例，请问这种写法是否符合规范？感谢解答。
你的写法完全符合Numpydoc的规范要求！
Numpydoc虽然没有专门针对“返回类实例”设置单独的条目说明，但它的Returns板块的设计逻辑本身就支持这种场景：
- 第一行的
index作为返回值的标识符，命名清晰易懂，符合Numpydoc对返回值名称的要求 - 第二行的描述明确说明了返回内容是
Index类实例，还补充了实例的核心用途（包含新建索引信息），这完全契合Numpydoc对返回值描述的核心要求——让使用者快速明确返回内容的类型和意义
另外给你两个小建议，能让文档更严谨易用：
- 如果
Index类是在当前模块或项目内的某个模块定义的，可以在描述里加上类的完整引用路径，比如meilisearch.client.Index，这样使用者能直接定位到类的定义 - 保持各板块（Parameters、Raises、Returns）下的描述文本缩进一致，你当前的示例已经做到了这一点，继续保持就好
内容的提问来源于stack exchange，提问作者Bidoubiwa
相关产品推荐
相关产品推荐
