MindSpore API Comment Specifications

MindSpore API Comment Specifications

Overview

MindSpore Python code comments comply with Google Python Style Guide. An API document is automatically generated by the Sphinx tool. For comment examples and support details, see Example Google Style Python Docstrings and Support for NumPy and Google style docstrings.
MindSpore C++ code needs to be compiled in Markdown files based on the namespace design.

Python API Comment Specifications

Comment Format

The comments of classes and methods are in the following format:

Summary.

More elaborate description.

Note:
    Description.

Args: 
    Arg1 (Type): Description. Default: xxx.
    Arg2 (Type): Description.

        - Sub-argument1 or Value1 of Arg2: Description. 
        - Sub-argument2 or Value2 of Arg2: Description. 

Returns:
    Type, description.

Raises:
    Type: Description.

Examples:
    >>> Sample Code

The format items are described as follows:

Summary: briefly describes the API function.
More elaborate description: describes the function and usage of an API in detail.
Note: describes precautions for using an API. Do not use Notes.
Args: API parameter information, including the parameter name, type, value range, and default value.
Returns: return value information, including the return value type.
Raises: exception information, including the exception type and meaning.
Examples: sample code

For comments of operators and cells, add Inputs and Outputs before Examples to describe the input and output types and shapes of the operators after instantiation. The input name can be the same as that in the example. It is recommended that the corresponding mathematical formula be provided in the comment.

Inputs:
    - **input_name1** (Type) - Description.
    - **input_name2** (Type) - Description.

Outputs:
    Type and shape, description.

Precautions

Overall Requirements
- The comment items required for a class or method are as follows: Summary, Args, Returns, and Raises. If a function does not contain related information (such as Args, Returns, and Raises), do not write None (for example, Raises: None), but directly omit the comment item.
- When an API is generated by directory, the comments in the __init__ file header are displayed at the beginning of the web page. When an API is generated by file, the comments at the beginning of the file are displayed at the beginning of the web page. The comments must contain the overall description of the corresponding modules.
- If a comment contains a backslash (\), change """ in the header to r""".
- Colon requirements: Keywords (such as Args and Returns) and parameter names (such as Arg1 or Arg2) are followed by colons (:). A colon must be followed by a space. The content of Summary and Returns cannot contain colons.
- Blank line requirements: A blank line is required between contents of different types (such as Args and Returns). A blank line is not required between contents of the same type (for example, Arg1 and Arg2). If the content is described in an unordered or ordered list, a blank line must be added between the content in the list and the content above the list.
- Space requirements: The newline characters of Args and Raises must be indented by four spaces. The sub-parameters or values of Args and line breaks for disordered or ordered content of Inputs, Outputs and Returns do not need indents and are aligned with the start position of the previous line. In Args, there must be a space between the parameter name and the ( of the type.
Args Comment
- Common parameter types are as follows:
  - Basic data types: int, float, bool, str, list, dict, set, tuple and numpy.ndarray.
  - dtype: For the value of mindspore.dtype, set this parameter to mindspore.dtype. For the value of the numpy type, set this parameter to numpy.dtype. Set other parameters based on the actual requirements.
  - One parameter with multiple optional types: Union [type 1, type 2], for example, Union[Tensor, Number].
  - List type: list[Specific type], for example, list[str].
  - The format of optional types is as follows: (Type, optional).
  - Other types: Tensor, other specific types, or method names.
Returns Comment
- If the return value type or dimension changes, describe the relationship between the return value and the input.
- If there are multiple return values, write them in different lines. The line difference is not displayed on the web page. The unordered list supports return values in different lines.
Examples Comment
- For the content in Examples, add >>> at the beginning of each line of code (including empty lines). It should not be added to the output result.
- Actual code needs to be provided in Examples. If you need to refer to other Examples, use Note.
- The comments of the ops operator are written in PyNative mode. If the operator can be executed, the execution result must be provided.
- Import can be omitted in the case of industry consensus, such as np and nn.
- If the import path is long or a user-defined alias is required, add from xxx import xxx as something or import xxx. If the import path is short, place it in the code.
Inputs and Outputs Comment
- If the data type is Tensor, describe the shape in the format of :math:(N, C, X).
Formula
- Line formula (in the middle of the singly occupied line)
```
.. math::

   formula
```
- Line-embedded formula (displayed together with other peer text, not in the middle)
```
xxx :math:`formula` xxx
```
- If the formula contains an underscored variable and the underscore is followed by multiple letters (for example, xxx_yyy) , select one of the following methods based on the site requirements:
  1. Multiple letters are enclosed in braces ({}), for example, xxx_{yyy}. The content following the underscore can be used as the subscript, which is displayed as $xxx_{yyy}$.
  2. If a backslash (\) is added before an underscore (_), for example, xxx\_yyy, the complete variable name is displayed as xxx_yyy.
Parent Class Method Display
- By default, the parent class method is not displayed.
- You can add :inherited-members: to the module of the RST file in the Sphinx project to specify the parent class method to be displayed. For details, see https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html.
Link
- Only the title (such as the name in the following example) is displayed. The detailed address is not displayed.
  
  Write a quotation in the following format:
```
`name`_
```
  Provide a link in the following format:
```
.. _`name`: https://xxx
```
  Note:
  - If there is a newline character, indent it. For details, see the following table.
  - There must be a space before https.
  Alternatively, you can use the following simplified format, that is, write only in the place where the reference is made.
```
`name <https://xxx>`_
```
- Display the detailed address:
```
https://xxx
```

Table (For details, see section https://sublime-and-sphinx-guide.readthedocs.io/en/latest/tables.html#list-table-directive.)

.. list-table:: Title            # Table title
 :widths: 25 25 25               # Table column width
 :header-rows: 1

 * - Heading row 1, column 1     # Table header
   - Heading row 1, column 2
   - Heading row 1, column 3
 * - Row 1, column 1
   -                             #The table is empty.
   - Row 1, column 3
 * - Row 2, column 1
   - Row 2, column 2
   - Row 2,
                                 # If a newline is required for the table content, add a blank line in the middle.
     column 3

Display effect:

By default, the detailed description is displayed in one line. If you need to display it in another line, write it in the form of a list or code-block.
- List mode:
```
- Content1
- Content2
- Content3
```
- Code-Block mode:
```
.. code-block::

   Content1
   Content2
   Content3
```

Python Example

Class

class Tensor(Tensor_):
    """
    Tensor is used for data storage.

    Tensor inherits tensor object in C++.
    Some functions are implemented in C++ and some functions are implemented in Python.

    Args:
        input_data (Tensor, float, int, bool, tuple, list, numpy.ndarray): Input data of the tensor.
        dtype (:class:`mindspore.dtype`): Input data should be None, bool or numeric type defined in `mindspore.dtype`.
            The argument is used to define the data type of the output tensor. If it is None, the data type of the
            output tensor will be as same as the `input_data`. Default: None.

    Outputs:
        Tensor, with the same shape as `input_data`.

    Examples:
        >>> # initialize a tensor with input data
        >>> t1 = Tensor(np.zeros([1, 2, 3]), mindspore.float32)
        >>> assert isinstance(t1, Tensor)
        >>> assert t1.shape == (1, 2, 3)
        >>> assert t1.dtype == mindspore.float32
        >>>
        >>> # initialize a tensor with a float scalar
        >>> t2 = Tensor(0.1)
        >>> assert isinstance(t2, Tensor)
        >>> assert t2.dtype == mindspore.float64
    """

    def __init__(self, input_data, dtype=None):
        ...

For details about the display effect, click here.

Method

def ms_function(fn=None, obj=None, input_signature=None):
    """
    Create a callable MindSpore graph from a python function.

    This allows the MindSpore runtime to apply optimizations based on graph.

    Args:
        fn (Function): The Python function that will be run as a graph. Default: None.
        obj (Object): The Python Object that provides the information for identifying the compiled function. Default:
            None.
        input_signature (MetaTensor): The MetaTensor which describes the input arguments. The MetaTensor specifies
            the shape and dtype of the Tensor and they will be supplied to this function. If input_signature
            is specified, each input to `fn` must be a `Tensor`. And the input parameters of `fn` cannot accept
            `**kwargs`. The shape and dtype of actual inputs should keep the same as input_signature. Otherwise,
            TypeError will be raised. Default: None.

    Returns:
        Function, if `fn` is not None, returns a callable function that will execute the compiled function; If `fn` is
        None, returns a decorator and when this decorator invokes with a single `fn` argument, the callable function is
        equal to the case when `fn` is not None.

    Examples:
        >>> def tensor_add(x, y):
        >>>     z = F.tensor_add(x, y)
        >>>     return z
        >>>
        >>> @ms_function
        >>> def tensor_add_with_dec(x, y):
        >>>     z = F.tensor_add(x, y)
        >>>     return z
        >>>
        >>> @ms_function(input_signature=(MetaTensor(mindspore.float32, (1, 1, 3, 3)),
        >>>                               MetaTensor(mindspore.float32, (1, 1, 3, 3))))
        >>> def tensor_add_with_sig(x, y):
        >>>     z = F.tensor_add(x, y)
        >>>     return z
        >>>
        >>> x = Tensor(np.ones([1, 1, 3, 3]).astype(np.float32))
        >>> y = Tensor(np.ones([1, 1, 3, 3]).astype(np.float32))
        >>>
        >>> tensor_add_graph = ms_function(fn=tensor_add)
        >>> out = tensor_add_graph(x, y)
        >>> out = tensor_add_with_dec(x, y)
        >>> out = tensor_add_with_sig(x, y)
    """
    ...

For details about the display effect, click here.

Formula

class Conv2d(_Conv):
    r"""
    2D convolution layer.

    Applies a 2D convolution over an input tensor which is typically of shape :math:`(N, C_{in}, H_{in}, W_{in})`,
    where :math:`N` is batch size, :math:`C_{in}` is channel number, and :math:`H_{in}, W_{in})` are height and width.
    For each batch of shape :math:`(C_{in}, H_{in}, W_{in})`, the formula is defined as:

    .. math::

        out_j = \sum_{i=0}^{C_{in} - 1} ccor(W_{ij}, X_i) + b_j,

    ...
    """

For details about the display effect, click here.

Link

class BatchNorm(PrimitiveWithInfer):
    r"""
    Batch Normalization for input data and updated parameters.

    Batch Normalization is widely used in convolutional neural networks. This operation
    applies Batch Normalization over input to avoid internal covariate shift as described
    in the paper `Batch Normalization: Accelerating Deep Network Training by Reducing Internal
    Covariate Shift <https://arxiv.org/abs/1502.03167>`_. It rescales and recenters the
    features using a mini-batch of data and the learned parameters which can be described
    in the following formula,

    ...
    """

For details about the display effect, click here.

C++ API Comment Specifications

The name of the Markdown file must be the same as that of the namespace.

The internal format of the Markdown file is as follows. For details, see Sample.

# The name of namespace

The link of header file.

## The name of class

The description of class.

The name of attribute or function.

The description of attribute or function.

15 kB Raw Blame History

MindSpore API Comment Specifications

Overview

Python API Comment Specifications

Comment Format

Precautions

Python Example

Class

Method

Formula

Link

C++ API Comment Specifications

15 kB

Raw Blame History