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:

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

```rst
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`). 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`, ```>>>``` 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.
    - 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)

        ```rst
        .. math::

            formula
        ```

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

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

        ```rst
        `name`_
        ```

        Provide a link in the following format:

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

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

    - Display the detailed address:

        ```rst
        https://xxx
        ```

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

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

        ```rst
        - Content1
        - Content2
        - Content3
        ```

    - Code-Block mode:

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