You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 

7.3 KiB

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[{类型名}]的描述时,默认假设列表或元组参数为同质的(即其中包含的所有元素具有相同的类型),若允许或需要列表、元组参数为异质的,需要在文字描述中说明;
  • 被分隔的类型如果是简单类型如intTensor等则|前后不需要添加空格,如果是多个复杂类型如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'])"
    """
    ...