community/security/comments_specification_en.md

# MindSpore API Comment Specifications

<!-- TOC -->

- [MindSpore API Comment Specifications](#mindspore-api-comment-specifications)
    - [Overview](#overview)
    - [Python API Comment Specifications](#python-api-comment-specifications)
        - [Comment Format](#comment-format)
        - [Precautions](#precautions)
        - [Python Example](#python-example)
            - [Class](#class)
            - [Method](#method)
            - [Formula](#formula)
            - [Link](#link)
    - [C++ API Comment Specifications](#c-api-comment-specifications)

<!-- /TOC -->

## Overview

- MindSpore Python code comments comply with [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html). An API document is automatically generated by the Sphinx tool. For comment examples and support details, see [Example Google Style Python Docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html) and [Support for NumPy and Google style docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html).
- 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:

```text
Summary.

More elaborate description.

.. warning::
    Warning description.

Note:
    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.
- `warning`: describes warnings for using an API to avoid negative consequences.
- `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`, `Outputs` and `Supported Platforms` before `Examples`.

- `Inputs` and `Outputs`: describes 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 to provide the corresponding mathematical formula in the comment.
- `Supported Platforms`: describes the hardware platforms supported by the operator. Add `` before and after the platform name, and use space to separate them when there are more than one.

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

Outputs:
    Type and shape, description.

Supported Platforms:
    ``Ascend`` ``GPU`` ``CPU``
```

### 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`).

        ```text
        High-Level API for Training or Testing.

        Args:
            network (Cell): A training or testing network.
            loss_fn (Cell): Objective function, if loss_fn is None, the
                network should contain the logic of loss and grads calculation, and the logic
                of parallel if needed. Default: None.

        Returns:
            function, original function.
        ```

        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.

        ```text
        Args:
            amp_level (str): Option for argument `level` in `mindspore.amp.build_train_network`, level for mixed
                precision training. Supports ["O0", "O2", "O3", "auto"]. Default: "O0".

                - O0: Do not change.
                - O2: Cast network to float16, keep batchnorm run in float32, using dynamic loss scale.
                - O3: Cast network to float16, with additional property 'keep_batchnorm_fp32=False'.
                - auto: Set to level to recommended level in different devices. Set level to O2 on GPU, Set
                  level to O3 Ascend. The recommended level is choose by the export experience, cannot
                  always generalize. User should specify the level for special network.

                O2 is recommended on GPU, O3 is recommended on Ascend.
        ```

    - Space requirements:

        The newline characters of `Args` and `Raises` must be indented by four spaces.

        ```text
        Args:
            lr_power (float): Learning rate power controls how the learning rate decreases during training,
                must be less than or equal to zero. Use fixed learning rate if `lr_power` is zero.
            use_locking (bool): If `True`, the var and accumulation tensors will be protected from being updated.
                Default: False.

        Raises:
            TypeError: If `lr`, `l1`, `l2`, `lr_power` or `use_locking` is not a float.
                If `use_locking` is not a bool.
                If dtype of `var`, `accum`, `linear` or `grad` is neither float16 nor float32.
                If dtype of `indices` is not int32.
        ```

        The following contents do not need indents and are aligned with the start position of the previous line.

        1. The sub-parameters or values of `Args`

            ```text
            Args:
                parallel_mode (str): There are five kinds of parallel modes, "stand_alone", "data_parallel",
                    "hybrid_parallel", "semi_auto_parallel" and "auto_parallel". Default: "stand_alone".

                    - stand_alone: Only one processor is working.
                    - data_parallel: Distributes the data across different processors.
                    - hybrid_parallel: Achieves data parallelism and model parallelism
                      manually.
                    - semi_auto_parallel: Achieves data parallelism and model parallelism by
                      setting parallel strategies.
            ```

        2. The line breaks for disordered or ordered content of `Inputs`, `Outputs` and `Returns`

            ```text
            Inputs:
                - **var** (Parameter) - The variable to be updated. The data type must be float16 or float32.
                - **accum** (Parameter) - The accumulation to be updated, must be same data type and shape as `var`.
                - **linear** (Parameter) - the linear coefficient to be updated, must be same data type and shape
                  as `var`.
                - **grad** (Tensor) - A tensor of the same type as `var`, for the gradient.
                - **indices** (Tensor) - A vector of indices in the first dimension of `var` and `accum`.
                  The shape of `indices` must be the same as `grad` in the first dimension. The type must be int32.

            Outputs:
                Tuple of 3 Tensor, the updated parameters.

                - **var** (Tensor) - Tensor, has the same shape
                  and data type as `var`.
                - **accum** (Tensor) - Tensor, has the same shape
                  and data type as `accum`.
                - **linear** (Tensor) - Tensor, has the same shape
                  and data type as `linear`.
            ```

        3. `Note` and `warning`

            ```text
            .. warning::
                This is warning text. Use a warning for information the user must
                understand to avoid negative consequences.

                If warning text runs over a line, make sure the lines wrap and are indented to
                the same level as the warning tag.
            ```

        In `Args`, there must be a space between the parameter name and the `(` of the type.

        ```text
        Args:
            lr (float): The learning rate value, must be positive.
        ```

- `Args` Comment
    - Common parameter types are as follows:
        - Basic data types: `int`, `float`, `bool`, `str`, `list`, `dict`, `set`, `tuple` and `numpy.ndarray`.

            ```text
            Args:
                arg1 (int): Some description.
                arg2 (float): Some description.
                arg3 (bool): Some description.
                arg4 (str): Some description.
                arg5 (list): Some description.
                arg6 (dict): Some description.
                arg7 (set): Some description.
                arg8 (tuple): Some description.
                arg9 (numpy.ndarray): Some description.
            ```

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

            ```text
            Args:
                arg1 (mindspore.dtype): Some description.
            ```

        - One parameter with multiple optional types: Union [type 1, type 2], for example, `Union[Tensor, Number]`.

            ```text
            Args:
                arg1 (Union[Tensor, Number]): Some description.
            ```

        - List type: list[Specific type], for example, `list[str]`.

            ```text
            Args:
                arg1 (list[str]): Some description.
            ```

        - The format of optional types is as follows: (Type, optional).

            ```text
            Args:
                arg1 (bool, optional): Some description.
            ```

        - Other types: Tensor, other specific types, or method names.

            ```text
            Args:
                arg1 (Tensor): Some description.
            ```

- `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.

        ```text
        Returns:
            - DatasetNode, the root node of the IR tree.
            - Dataset, the root dataset of the IR tree.
        ```

- `Examples` Comment
    - For the content in `Examples`, ```>>>``` should be added at the beginning of each line of code. For multiple lines (including classes, function definitions or manual switch line) and blank lines, ```...``` is needed at the beginning of these lines. There is no need to add any symbols at the beginning of the output result line.

         ```text
        Examples:
            >>> import mindspore as ms
            >>> import mindspore.nn as nn
            >>> class Net(nn.Cell):
            ...     def __init__(self, dense_shape):
            ...         super(Net, self).__init__()
            ...         self.dense_shape = dense_shape
            ...     def construct(self, indices, values):
            ...         x = SparseTensor(indices, values, self.dense_shape)
            ...         return x.values, x.indices, x.dense_shape
            ...
            >>> indices = Tensor([[0, 1], [1, 2]])
            >>> values = Tensor([1, 2], dtype=ms.float32)
            >>> out = Net((3, 4))(indices, values)
            >>> print(out[0])
            [1. 2.]
            >>> print(out[1])
            [[0 1]
             [1 2]]
            >>> print(out[2])
            (3, 4)
        ```

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

        ```text
        .. math::

            formula
        ```

    - Line-embedded formula (displayed together with other peer text, not in the middle)

        ```text
        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:

        ```text
        `name`_
        ```

        Provide a link in the following format:

        ```text
        .. _`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.

        ```text
        `name <https://xxx>`_
        ```

    - Display the detailed address:

        ```text
        https://xxx
        ```

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

    ```text
    .. 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:

    ![image](./resource/list_table.png)

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

        ```text
        - Content1
        - Content2
        - Content3
        ```

    - Code-Block mode:

        ```text
        .. code-block::

        Content1
        Content2
        Content3
        ```

### Python Example

#### Class

```python
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](https://www.mindspore.cn/doc/api_python/en/master/mindspore/mindspore.html#mindspore.Tensor).

#### Method

```python
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](https://www.mindspore.cn/doc/api_python/en/master/mindspore/mindspore.html#mindspore.ms_function).

#### Formula

```python
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](https://www.mindspore.cn/doc/api_python/en/master/mindspore/mindspore.nn.html#mindspore.nn.Conv2d).

#### Link

```python
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](https://www.mindspore.cn/doc/api_python/en/master/mindspore/mindspore.ops.html#mindspore.ops.BatchNorm).

## 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](https://www.mindspore.cn/doc/api_cpp/en/master/lite.html).

  ```markdown
  # 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.

  ```