pythonnumpydoc

Numpydoc style convention when returning an instance of a class

I'm following the numpydoc style guide to document my code but I cannot find the convention for returning an instance of a 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  
"""

In the returns section, as you can see, I return an instance of Index. Is this the way to document it ?

Thanks in advance

Solution

  • From the 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.

    So for your example you would use Index as the type, together with an optional name:

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

    Here the index : part is optional.