7.3 KiB

Raw Permalink Blame History

PaddleRS代码注释规范

1 注释规范

函数的docstring由5个模块构成：

函数功能描述；
函数参数；
（可选）函数返回值；
（可选）函数可能抛出的异常；
（可选）使用示例。

类的docstring也由5个模块构成：

类功能描述；
实例化类所需参数；
（可选）实例化类得到的对象；
（可选）实例化类时可能抛出的异常；
（可选）使用示例。

以下将详细叙述每个模块的规范。

1.1 函数/类功能描述

目标是让用户能快速看懂。该模块又可以拆解为3个部分，功能叙述 + 计算公式 + 注解。

功能叙述：描述该函数或类的具体功能。由于用户不一定具有相应背景知识，所以需要补充必要的细节。
（可选）计算公式：如有需要，给出函数的计算公式。公式建议以LaTex文法编写。
（可选）注解：如需要特殊说明，可以在该部分给出。

示例：

"""
    Add two tensors element-wise. The equation is:

        out = x + y

    Note: This function supports broadcasting. If you want know more about broadcasting, please
        refer to :ref:`user_guide_broadcasting` .
"""

1.2 函数参数/类构造参数

要解释清楚每个参数的类型、含义和默认值（如果有）。

注意事项：

可选参数要备注optional，例如：name (str|None, optinoal)；
若参数具有多种可选类型，用|分隔；
参数名和类型之间需要空1格；
可使用list[{类型名}]和tuple[{类型名}]的方式表示包含某种类型对象的列表或元组（注意大小写），例如list[int]表示包含int类型元素的列表，tuple[int|float]等价于tuple[int] | tuple[float]；
使用list[{类型名}]和tuple[{类型名}]的描述时，默认假设列表或元组参数为同质的（即其中包含的所有元素具有相同的类型），若允许或需要列表、元组参数为异质的，需要在文字描述中说明；
被分隔的类型如果是简单类型如int、Tensor等则|前后不需要添加空格，如果是多个复杂类型如list[int]和tuple[float]则需要在|前后添加空格；
对于有默认值的参数，至少要讲清楚在取默认值时的逻辑，而不仅仅是介绍这个参数是什么以及默认值是什么。

示例：

"""
    Args:
        x (Tensor|np.ndarray): Input tensor or numpy array.
        points (list[int] | tuple[int|float]): List or tuple of data points.
        name (str|None, optional): Name for the operation. If None, the operation will not be named.
            Default: None.
"""

1.3 返回值/构造对象

对于函数返回值，先描述返回值的类型（用(``)包围，语法与参数类型描述一致），然后说明返回值的含义。对于实例化类得到的对象，无需说明类型。

示例1：

"""
    Returns:
        (tuple): When label is None, it returns (im, im_info); otherwise it returns (im, im_info, label).
"""

示例2：

"""
    Returns:
        (N-D Tensor): A location into which the result is stored.
"""

示例3（类定义中）：

"""
    Returns:
        A callable object of Activation.
"""

1.4 可能抛出的异常

需给出异常类型和抛出异常的条件。

示例：

"""
    Raises:
        ValueError: When memory() is called outside block().
        TypeError: When init is set and is not a Variable.
"""

1.5 使用示例

为函数或类的各种使用场景尽可能地提供示例，并在注释中给出执行代码预期得到的结果。

要求：用户复制示例代码到脚本即可运行。注意需要加必要的import。

单example示例：

"""
    Examples:

            import paddle
            import numpy as np

            paddle.enable_imperative()
            np_x = np.array([2, 3, 4]).astype('float64')
            np_y = np.array([1, 5, 2]).astype('float64')
            x = paddle.imperative.to_variable(np_x)
            y = paddle.imperative.to_variable(np_y)

            z = paddle.add(x, y)
            np_z = z.numpy()
            # [3., 8., 6. ]

            z = paddle.add(x, y, alpha=10)
            np_z = z.numpy()
            # [12., 53., 24. ]
"""

多examples示例：

"""
    Examples 1:

        from paddleseg.cvlibs.manager import ComponentManager

        model_manager = ComponentManager()

        class AlexNet: ...
        class ResNet: ...

        model_manager.add_component(AlexNet)
        model_manager.add_component(ResNet)

        # Alternatively, pass a sequence:
        model_manager.add_component([AlexNet, ResNet])
        print(model_manager.components_dict)
        # {'AlexNet': <class '__main__.AlexNet'>, 'ResNet': <class '__main__.ResNet'>}

    Examples 2:

        # Use it as a Python decorator.
        from paddleseg.cvlibs.manager import ComponentManager

        model_manager = ComponentManager()

        @model_manager.add_component
        class AlexNet: ...

        @model_manager.add_component
        class ResNet: ...

        print(model_manager.components_dict)
        # {'AlexNet': <class '__main__.AlexNet'>, 'ResNet': <class '__main__.ResNet'>}
"""

1.6 语法

措词准确，使用深度学习领域通用的词汇和说法。
语句通顺，符合英文语法。
文档中对同一事物的表述要做到前后一致，比如避免有时用label、有时用ground truth。

1.7 其他注意事项

不同模块间以1个空行分隔。
注意首字母大写以及添加标点符号（尤其是句号），符合英语语法规则。
在代码示例内容中可适当加空行以体现层次感。
对于注释中出现的输入参数名、输入参数的属性或方法以及文件路径，使用反引号```包围。
每个模块的标题/子标题和具体内容之间需要有换行和缩进，Examples:标题与示例代码内容之间插入1个空行。
单段描述跨行时需要使用悬挂式缩进。

2 完整docstring示例

class Activation(nn.Layer):
    """
    The wrapper of activations.

    Args:
        act (str, optional): Activation name in lowercase. It must be one of {'elu', 'gelu',
            'hardshrink', 'tanh', 'hardtanh', 'prelu', 'relu', 'relu6', 'selu', 'leakyrelu', 'sigmoid',
            'softmax', 'softplus', 'softshrink', 'softsign', 'tanhshrink', 'logsigmoid', 'logsoftmax',
            'hsigmoid'}. Default: None, means identical transformation.

    Returns:
        A callable object of Activation.

    Raises:
        KeyError: When parameter `act` is not in the optional range.

    Examples:

        from paddleseg.models.common.activation import Activation

        relu = Activation("relu")
        print(relu)
        # <class 'paddle.nn.layer.activation.ReLU'>

        sigmoid = Activation("sigmoid")
        print(sigmoid)
        # <class 'paddle.nn.layer.activation.Sigmoid'>

        not_exit_one = Activation("not_exit_one")
        # KeyError: "not_exit_one does not exist in the current dict_keys(['elu', 'gelu', 'hardshrink',
        # 'tanh', 'hardtanh', 'prelu', 'relu', 'relu6', 'selu', 'leakyrelu', 'sigmoid', 'softmax',
        # 'softplus', 'softshrink', 'softsign', 'tanhshrink', 'logsigmoid', 'logsoftmax', 'hsigmoid'])"
    """
    ...

7.3 KiB Raw Permalink Blame History