update comments specification of example

Signed-off-by: Ting Wang <kathy.wangting@huawei.com>

security/comments_specification.md

@@ -17,6 +17,7 @@
 <!-- /TOC -->
 
 ## 总体说明
+
 - MindSpore Python代码注释遵循[Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)，由Sphinx工具自动生成API文档，注释样例和支持情况可参考[Example Google Style Python Docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html)和[Support for NumPy and Google style docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)。
 - MindSpore C++代码需按照命名空间的设计，分别编写Markdown文件。
 
@@ -26,7 +27,7 @@
 
 类和方法的注释都采用如下格式：
 
-```
+```rst
 Summary.
 
 More elaborate description.
@@ -34,12 +35,12 @@ More elaborate description.
 Note:
     Description.
 
-Args: 
+Args:
     Arg1 (Type): Description. Default: xxx.
     Arg2 (Type): Description.
 
-        - Sub-argument1 or Value1 of Arg2: Description. 
-        - Sub-argument2 or Value2 of Arg2: Description. 
+        - Sub-argument1 or Value1 of Arg2: Description.
+        - Sub-argument2 or Value2 of Arg2: Description.
 
 Returns:
     Type, description.
@@ -52,6 +53,7 @@ Examples:
 ```
 
 其中，  
+
 - `Summary`：简单描述该接口的功能。
 - `More elaborate description`：详细描述该接口的功能和如何使用等信息。
 - `Note`：描述使用该接口时需要注意的事项。特别注意不能写成`Notes`。
@@ -61,7 +63,8 @@ Examples:
 - `Examples`：样例代码。
 
 针对算子和Cell的注释，需要在`Examples`前添加`Inputs`和`Outputs`两项内容，用于描述实例化后，算子的输入和输出的类型和shape，输入名可以和样例相同。建议在注释中给出对应的数学公式。
-```
+
+```rst
 Inputs:
     - **input_name1** (Type) - Description.
     - **input_name2** (Type) - Description.
@@ -71,6 +74,7 @@ Outputs:
 ```
 
 ### 注意事项
+
 - 整体要求
     - 类或方法必须书写的注释项有：`Summary`、`Args`、`Returns`和`Raises`。如果函数中没有相关信息（如`Args`、`Returns`和`Raises`等），不需要写None（如`Raises：None`），直接省略注释项即可。
     - 以目录为粒度生成API时，__init__文件头部的注释内容会呈现在网页开头；以文件为粒度生成API时，该文件头部的注释内容会呈现在网页开头。这些注释内容需包含相应模块的整体说明。
@@ -90,96 +94,113 @@ Outputs:
     - 如果返回值类型或维度发生变化，需要说明返回值与输入的关系。
     - 多个返回值时，分行写，网页显示时不分行，无序列表的方式可支持分行。
 - `Examples`注释说明
-    - `Examples`中的内容需在每行代码开头加上```>>> ```（包括空行），输出结果不需要加。
+    - `Examples`中的内容需在每行代码开头加上```>>>```，多行代码（含类或函数定义、人为换行等）或空行的开头需加上```...```，输出结果行开头不需要加任何符号。
     - `Examples`中需提供实际的代码，如果需提示参考其他Examples，请使用Note。
     - ops算子注释采用PyNative模式写作，可运行的需给出运行结果。
     - 业界共识的情况可省略import，如np、nn等。
     - 导入路径较长和必须自定义别名的导入需要加`from xxx import xxx as something`或`import xxx`，导入路径短的尽量放到代码中。
 - `Inputs`和`Outputs`注释说明
-    
-    -  类型是Tensor时，需描述shape，并按:math:`(N, C, X)`格式写作。
+
+    - 类型是Tensor时，需描述shape，并按:math:`(N, C, X)`格式写作。
 - 公式
     - 行公式（单独占一行，居中）
-      ```
+
+      ```rst
       .. math::
 
          formula
       ```
+
     - 行内嵌公式（与其他同行文字显示在一起，不居中）
-      ```
+
+      ```rst
       xxx :math:`formula` xxx
       ```
+
     - 公式中带有含下划线的变量，且下划线后存在多个字母（如xxx_yyy），请根据实际需要选择以下其中一种方式。
         1. 多个字母用{}括起来（如xxx_{yyy}），可将下划线后的内容作为下标，显示为$xxx_{yyy}$。
         2. 在下划线前增加反斜杠（如xxx\\_yyy），可将完整显示变量名称，显示为xxx_yyy。
 - 父类方法的显示
-  - 默认不显示父类方法。
-  - 可通过在Sphinx工程rst文件的模块下添加`:inherited-members:`，指定需要显示父类方法，详细可参考<https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>。
+    - 默认不显示父类方法。
+    - 可通过在Sphinx工程rst文件的模块下添加`:inherited-members:`，指定需要显示父类方法，详细可参考<https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>。
 - 链接
-  - 只显示标题（如例子中的name），不显示详细地址。
+    - 只显示标题（如例子中的name），不显示详细地址。
 
-    引用的地方需这样写：
-    ```
-    `name`_
-    ```
+        引用的地方需这样写：
 
-    提供链接的地方需这样写：
-    ```
-    .. _`name`: https://xxx
-    ```
-    注意：
-    - 如有换行请注意缩进，参考下方具体示例。
-    - https前需有空格。
+        ```rst
+        `name`_
+        ```
+
+        提供链接的地方需这样写：
+
+        ```rst
+        .. _`name`: https://xxx
+        ```
+
+        注意：
+        - 如有换行请注意缩进，参考下方具体示例。
+        - https前需有空格。
+
+        或者可以采用以下简化写法，只在引用的地方写即可。
+
+        ```rst
+        `name <https://xxx>`_
+        ```
+
+    - 直接显示详细地址。
+
+        ```rst
+        https://xxx
+        ```
 
-    或者可以采用以下简化写法，只在引用的地方写即可。
-    ```
-    `name <https://xxx>`_
-    ```
-  - 直接显示详细地址。
-    ```
-    https://xxx
-    ```
 - 表格（详细可参考<https://sublime-and-sphinx-guide.readthedocs.io/en/latest/tables.html#list-table-directive>）
-  ```
-  .. list-table:: Title            # 表格标题
-   :widths: 25 25 25               # 表格列宽
-   :header-rows: 1
-
-   * - Heading row 1, column 1     # 表头
-     - Heading row 1, column 2
-     - Heading row 1, column 3
-   * - Row 1, column 1
-     -                             # 表格内容为空
-     - Row 1, column 3
-   * - Row 2, column 1
-     - Row 2, column 2
-     - Row 2,
-                                   # 表格内容如需换行，在中间增加一个空行
-       column 3
-  ```
 
-  显示效果：
+    ```rst
+    .. list-table:: Title            # 表格标题
+    :widths: 25 25 25               # 表格列宽
+    :header-rows: 1
+
+    * - Heading row 1, column 1     # 表头
+        - Heading row 1, column 2
+        - Heading row 1, column 3
+    * - Row 1, column 1
+        -                             # 表格内容为空
+        - Row 1, column 3
+    * - Row 2, column 1
+        - Row 2, column 2
+        - Row 2,
+                                    # 表格内容如需换行，在中间增加一个空行
+        column 3
+    ```
+
+    显示效果：
+
+    ![image](./resource/list_table.png)
 
-  ![image](./resource/list_table.png)
 - 详细说明默认不换行，如需换行，需以列表或code-block的方式写作。
-  - 列表方式：
-    ```
-    - Content1
-    - Content2
-    - Content3
-    ```
+    - 列表方式：
 
-  - code-block方式：
-    ```
-    .. code-block::
+        ```rst
+        - Content1
+        - Content2
+        - Content3
+        ```
 
-       Content1
-       Content2
-       Content3
-    ```
+    - code-block方式：
+
+        ```rst
+        .. code-block::
+
+        Content1
+        Content2
+        Content3
+        ```
 
 ### Python示例
+
 #### 类
+
 ```python
 class Tensor(Tensor_):
     """
@@ -203,7 +224,7 @@ class Tensor(Tensor_):
         >>> 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)
@@ -217,6 +238,7 @@ class Tensor(Tensor_):
 显示效果可访问[这里](https://www.mindspore.cn/doc/api_python/zh-CN/master/mindspore/mindspore.html#mindspore.Tensor)。
 
 #### 方法
+
 ```python
 def ms_function(fn=None, obj=None, input_signature=None):
     """
@@ -241,23 +263,23 @@ def ms_function(fn=None, obj=None, input_signature=None):
 
     Examples:
         >>> def tensor_add(x, y):
-        >>>     z = F.tensor_add(x, y)
-        >>>     return z
-        >>>
+        ...     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
-        >>>
+        ...     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))))
+        ...                               MetaTensor(mindspore.float32, (1, 1, 3, 3))))
         >>> def tensor_add_with_sig(x, y):
-        >>>     z = F.tensor_add(x, y)
-        >>>     return z
-        >>>
+        ...     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)
@@ -269,6 +291,7 @@ def ms_function(fn=None, obj=None, input_signature=None):
 显示效果可访问[这里](https://www.mindspore.cn/doc/api_python/zh-CN/master/mindspore/mindspore.html#mindspore.ms_function)。
 
 #### 公式
+
 ```python
 class Conv2d(_Conv):
     r"""
@@ -289,6 +312,7 @@ class Conv2d(_Conv):
 显示效果可访问[这里](https://www.mindspore.cn/doc/api_python/zh-CN/master/mindspore/mindspore.nn.html#mindspore.nn.Conv2d)。
 
 #### 链接
+
 ```python
 class BatchNorm(PrimitiveWithInfer):
     r"""
@@ -311,7 +335,8 @@ class BatchNorm(PrimitiveWithInfer):
 
 - Markdown文件命名需与命名空间相同。
 - Markdown文件内部格式如下，可参考[样例](https://www.mindspore.cn/doc/api_cpp/zh-CN/master/lite.html)。
-  ```
+
+  ```markdown
   # The name of namespace
   
   The link of header file.
@@ -324,4 +349,4 @@ class BatchNorm(PrimitiveWithInfer):
 
   The description of attribute or function.
   
-  ```
+  ```

security/comments_specification_en.md

@@ -17,6 +17,7 @@
 <!-- /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.
 
@@ -26,7 +27,7 @@
 
 The comments of classes and methods are in the following format:
 
-```
+```rst
 Summary.
 
 More elaborate description.
@@ -34,12 +35,12 @@ More elaborate description.
 Note:
     Description.
 
-Args: 
+Args:
     Arg1 (Type): Description. Default: xxx.
     Arg2 (Type): Description.
 
-        - Sub-argument1 or Value1 of Arg2: Description. 
-        - Sub-argument2 or Value2 of Arg2: Description. 
+        - Sub-argument1 or Value1 of Arg2: Description.
+        - Sub-argument2 or Value2 of Arg2: Description.
 
 Returns:
     Type, description.
@@ -52,6 +53,7 @@ Examples:
 ```
 
 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`.
@@ -61,7 +63,8 @@ The format items are described as follows:
 - `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.
-```
+
+```rst
 Inputs:
     - **input_name1** (Type) - Description.
     - **input_name2** (Type) - Description.
@@ -71,6 +74,7 @@ Outputs:
 ```
 
 ### 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.
@@ -90,96 +94,113 @@ Outputs:
     - 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.
+    - For the content in `Examples`, add ```>>>``` at the beginning of each line of code, and add ```...``` at the beginning of each line of multiple lines of code (including class or function definitions, artificial line breaks, etc.) or empty lines. No sign is required 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)
-      ```
-      .. math::
 
-         formula
-      ```
+        ```rst
+        .. math::
+
+            formula
+        ```
+
     - Line-embedded formula (displayed together with other peer text, not in the middle)
-      ```
-      xxx :math:`formula` xxx
-      ```
+
+        ```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>.
+    - 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.
+    - 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`_
-    ```
+        Write a quotation in the following format:
 
-    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.
+        ```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
+        ```
 
-    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:
+    ```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)
 
-  ![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:
-    ```
-    - Content1
-    - Content2
-    - Content3
-    ```
+    - List mode:
 
-  - Code-Block mode:
-    ```
-    .. code-block::
+        ```rst
+        - Content1
+        - Content2
+        - Content3
+        ```
 
-       Content1
-       Content2
-       Content3
-    ```
+    - Code-Block mode:
+
+        ```rst
+        .. code-block::
+
+        Content1
+        Content2
+        Content3
+        ```
 
 ### Python Example
+
 #### Class
+
 ```python
 class Tensor(Tensor_):
     """
@@ -203,7 +224,7 @@ class Tensor(Tensor_):
         >>> 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)
@@ -217,6 +238,7 @@ class Tensor(Tensor_):
 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):
     """
@@ -241,23 +263,23 @@ def ms_function(fn=None, obj=None, input_signature=None):
 
     Examples:
         >>> def tensor_add(x, y):
-        >>>     z = F.tensor_add(x, y)
-        >>>     return z
-        >>>
+        ...     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
-        >>>
+        ...     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))))
+        ...                               MetaTensor(mindspore.float32, (1, 1, 3, 3))))
         >>> def tensor_add_with_sig(x, y):
-        >>>     z = F.tensor_add(x, y)
-        >>>     return z
-        >>>
+        ...     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)
@@ -269,6 +291,7 @@ def ms_function(fn=None, obj=None, input_signature=None):
 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"""
@@ -289,6 +312,7 @@ class Conv2d(_Conv):
 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"""
@@ -311,7 +335,8 @@ For details about the display effect, click [here](https://www.mindspore.cn/doc/
 
 - 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.
@@ -324,4 +349,4 @@ For details about the display effect, click [here](https://www.mindspore.cn/doc/
 
   The description of attribute or function.
   
-  ```
+  ```