python - 返回类实例时的 Numpydoc 样式约定

Question

我正在按照numpydoc 样式指南记录我的代码，但我找不到返回类实例的约定：

"""Create an index in the meilisearch API.  
If the argument \`uid\` isn't passed in, it will be generated by meilisearch.  
If the argument \`name\` isn't passed in, it will raise an error.  
Parameters  
----------  
name: str  
  Name of the index  
uid: str, optional  
  Unique identifier of the index  
Raises  
------  
HTTPError  
If no name is passed in as a parameter.  
HTTPError  
In case of any other error found here https://docs.meilisearch.com/references/#errors-status-code  
Returns  
-------  
index  
an instance of Index containing the information of the newly created index  
"""

如您所见，在返回部分中，我返回了一个 Index 实例。这是记录它的方式吗？

提前致谢

Answer 1

从numpydoc 风格指南：

5. Returns
返回值及其类型的说明。类似于参数部分，除了每个返回值的名称是可选的。每个返回值的类型始终是必需的。

Returns
-------
int
    Description of anonymous integer return value.

因此，对于您的示例，您将使用Index类型以及可选名称：

Returns
-------
index : Index
    <some meaningful description here>

这里的index :部分是可选的。