使用文档字符串的 Python 多行注释

在 Python 中，文档字符串是一个多行字符串，它位于函数、方法、模块或类的开头。文档字符串允许程序员说明该函数、方法、模块或类的用途、参数以及返回值信息。

如何编写文档字符串

编写文档字符串时需要注意以下几点：

1. 文档字符串应该放在函数、方法、模块或类的开头，并且在该架构下采用缩进。

2. 第一行应该包含一句简洁明了的描述，该描述应该以大写字母开头但不需要以句号结尾。

3. 第二行应该是空白行。

4. 如果文档字符串有多行，则在下一行以及后续行的开头应该是一个缩进，该缩进的数量应该与该模块下的其他任何代码行的缩进数量相同。

示例

def square(number):
    """
    This function takes a number and returns its square.

    Args:
        number (int): The number which needs to be squared.

    Returns:
        int: The square of the given number.

    Examples:
        >>> square(3)
        9
        >>> square(5)
        25
    """
    return number ** 2

解释

在上面的示例中，我们定义了一个名为 square 的函数，它将一个数平方，并返回结果。我们使用文档字符串来提供以下有关此函数的信息：

1. 概述：我们使用了一句简短的描述，以介绍此函数的用法和作用。

2. 参数：我们使用 Args 标题说明了此函数接受一个 number 参数，用于指定欲平方的数字。

3. 返回值：我们使用 Returns 标题说明此函数返回一个整数，表明给定数字的平方。

4. 示例代码：我们提供了几个示例，使用代码的方式演示了此函数的用法。

在编写文档字符串时，请确保内容明确、简洁，同时也要准确地描述函数的功能、行为和预期结果。文档字符串也可以作为文档生成器的基础，帮助您轻松地生成函数库和模块的详细文档。