From 32231d621efcd37aa6c2d404e70cdb26eb623498 Mon Sep 17 00:00:00 2001 From: yingchen Date: Fri, 20 Aug 2021 15:53:35 +0800 Subject: [PATCH] update api comment --- security/comments_specification_en.md | 15 ++++++++------- security/comments_specification_zh_cn.md | 15 ++++++++------- 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/security/comments_specification_en.md b/security/comments_specification_en.md index 05213fd..515d226 100644 --- a/security/comments_specification_en.md +++ b/security/comments_specification_en.md @@ -57,7 +57,7 @@ Examples: The format items are described as follows: -- `Summary`: briefly describes the API function. +- `Summary`: briefly describes the API function. If the description begins with a verb, the module must use the same verb form, the first person (the original form of the verb) or the third person (add an "s" after the verb), and the first person is recommended. - `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`. @@ -89,6 +89,7 @@ Supported Platforms: - 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"""`. + - If the comment begins with a verb, the module must use the same verb form, the first person (the original form of the verb) or the third person (add an "s" after the verb), and the first person is recommended. - 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: @@ -429,7 +430,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). +For details about the display effect, click [here](https://www.mindspore.cn/docs/api/en/master/api_python/mindspore/mindspore.Tensor.html). #### Method @@ -482,7 +483,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). +For details about the display effect, click [here](https://www.mindspore.cn/docs/api/en/master/api_python/mindspore/mindspore.ms_function.html). #### Formula @@ -491,7 +492,7 @@ 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})`, + Apply 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: @@ -503,7 +504,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). +For details about the display effect, click [here](https://www.mindspore.cn/docs/api/en/master/api_python/nn/mindspore.nn.Conv2d.html). #### Link @@ -523,12 +524,12 @@ class BatchNorm(PrimitiveWithInfer): """ ``` -For details about the display effect, click [here](https://www.mindspore.cn/doc/api_python/en/master/mindspore/mindspore.ops.html#mindspore.ops.BatchNorm). +For details about the display effect, click [here](https://www.mindspore.cn/docs/api/en/master/api_python/ops/mindspore.ops.BatchNorm.html). ## 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). +- The internal format of the Markdown file is as follows. For details, see [Sample](https://www.mindspore.cn/lite/api/en/master/api_cpp/mindspore.html). ```markdown # The name of namespace diff --git a/security/comments_specification_zh_cn.md b/security/comments_specification_zh_cn.md index 97ba978..15c6876 100644 --- a/security/comments_specification_zh_cn.md +++ b/security/comments_specification_zh_cn.md @@ -57,7 +57,7 @@ Examples: 其中， -- `Summary`：简单描述该接口的功能。 +- `Summary`：简单描述该接口的功能。若该描述为动词开头，模块内需统一用第一人称（即动词原形）或第三人称（即动词后加s），推荐用第一人称。 - `More elaborate description`：详细描述该接口的功能和如何使用等信息。 - `warning`：描述使用该接口时需要警告的事项，以免造成负面影响。 - `Note`：描述使用该接口时需要注意的事项。特别注意不能写成`Notes`。 @@ -89,6 +89,7 @@ Supported Platforms: - 类或方法必须书写的注释项有：`Summary`、`Args`、`Returns`和`Raises`。如果函数中没有相关信息（如`Args`、`Returns`和`Raises`等），不需要写None（如`Raises：None`），直接省略注释项即可。 - 以目录为粒度生成API时，__init__文件头部的注释内容会呈现在网页开头；以文件为粒度生成API时，该文件头部的注释内容会呈现在网页开头。这些注释内容需包含相应模块的整体说明。 - 注释中包含反斜杠时，需要将头部的`"""`改成`r"""`。 + - 注释内容若为动词开头，模块内需统一用第一人称（即动词原形）或第三人称（即动词后加s），推荐用第一人称。 - 冒号要求：关键字（如`Args`、`Returns`等）后面有冒号":"；参数名（如`Arg1`、`Arg2`等）后面有冒号":"，冒号后需有空格。`Summary`和`Returns`的内容中不能包含冒号。 - 空行要求： @@ -429,7 +430,7 @@ class Tensor(Tensor_): ... ``` -显示效果可访问[这里](https://www.mindspore.cn/doc/api_python/zh-CN/master/mindspore/mindspore.html#mindspore.Tensor)。 +显示效果可访问[这里](https://www.mindspore.cn/docs/api/zh-CN/master/api_python/mindspore/mindspore.Tensor.html)。 #### 方法 @@ -482,7 +483,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)。 +显示效果可访问[这里](https://www.mindspore.cn/docs/api/zh-CN/master/api_python/mindspore/mindspore.ms_function.html)。 #### 公式 @@ -491,7 +492,7 @@ 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})`, + Apply 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: @@ -503,7 +504,7 @@ class Conv2d(_Conv): """ ``` -显示效果可访问[这里](https://www.mindspore.cn/doc/api_python/zh-CN/master/mindspore/mindspore.nn.html#mindspore.nn.Conv2d)。 +显示效果可访问[这里](https://www.mindspore.cn/docs/api/zh-CN/master/api_python/nn/mindspore.nn.Conv2d.html)。 #### 链接 @@ -523,12 +524,12 @@ class BatchNorm(PrimitiveWithInfer): """ ``` -显示效果可访问[这里](https://www.mindspore.cn/doc/api_python/zh-CN/master/mindspore/mindspore.ops.html#mindspore.ops.BatchNorm)。 +显示效果可访问[这里](https://www.mindspore.cn/docs/api/zh-CN/master/api_python/ops/mindspore.ops.BatchNorm.html)。 ## C++ API注释规范 - Markdown文件命名需与命名空间相同。 -- Markdown文件内部格式如下，可参考[样例](https://www.mindspore.cn/doc/api_cpp/zh-CN/master/lite.html)。 +- Markdown文件内部格式如下，可参考[样例](https://www.mindspore.cn/lite/api/zh-CN/master/api_cpp/mindspore.html)。 ```markdown # The name of namespace