返回 class 实例时的 Numpydoc 样式约定

Question

我正在按照 numpydoc style guide 来记录我的代码，但是我找不到 returning class 实例的约定：


"""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  
"""

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

提前致谢

Answer 1

来自numpydoc style guide：

5. Returns
Explanation of the returned values and their types. Similar to the Parameters section, except the name of each return value is optional. The type of each return value is always required.

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

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

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

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

返回 class 实例时的 Numpydoc 样式约定

Numpydoc style convention when returning an instance of a class

python

numpydoc