Python Docstring 使用

当我们写代码的时候，注释往往是必不可少的，这点尤其针对需要共享代码的情况下。Docstrings 就是为了解决这个问题而生的。

什么是 Docstrings？

Docstrings 是可描述模块、类、函数及方法的文本，它们不仅仅只是注释。可以使用它们来生成文档，也可以通过某些工具来检测文档的正确性。

Docstrings 的样式

Python 支持两种不同的 Docstrings 编写方式：一种是单行的 Docstrings，另一种是多行的 Docstrings。

单行 Docstrings

单行的 Docstrings 非常适合简短的函数和方法，它们直接被放在函数或方法的第一行顶部，用三个双引号包裹起来。

def my_func():
    """This is a single line Docstring"""
    pass

多行 Docstrings

多行的 Docstrings 非常适合描述模块、大型函数和类，它们可以根据需要被放在模块、类、函数的第一行顶部，也可以在顶部添加空行。

对于多行的 Docstrings，有两种常见的风格：Google 风格 和 Numpy 风格。

Google 风格

Google 风格的 Docstrings 将单行摘要和详细描述分成两个部分，并使用空行分隔。

def my_func():
    """This is a summary line.
    
    This is a detailed description that can span multiple lines.
    """
    pass

Numpy 风格

Numpy 风格的 Docstrings 将摘要和详细描述放在同一行，使用冒号分隔，并用空行分隔详细描述。

def my_func():
    """This is a summary line with a numpy-style docstring.
    
    Parameters:
    arg1 (int): Description of arg1
    arg2 (str): Description of arg2
    
    Returns:
    bool: Description of return value
    """
    pass

Docstrings 的示例

下面是一个简单的 Python 函数，它使用了 Google 风格的 Docstrings：

def multiply_numbers(a: int, b: int) -> int:
    """Multiply two numbers and return the result.
    
    Args:
        a (int): The first number to be multiplied.
        b (int): The second number to be multiplied.
    
    Returns:
        int: The product of a and b.
    """
    return a * b

生成文档

在 Python 中，可以使用 help() 函数来显示由 Docstrings 自动创建的文档。也可以使用 pydoc 命令行工具来生成文档。

python -m pydoc <module_name>

总结

我们在这里讲述了 Python 的 Docstrings 使用方法以及样式，它们是 Python 中用于生成文档的非常重要的工具。在写代码之前，我们需要思考一下如何使用以及编写 Docstrings，这会帮助我们构建更好的文档，使我们的代码更加轻松易懂。