如何为Python函数添加文档字符串

Python函数的文档字符串是一种特殊的注释，用于描述函数的操作、参数和返回值等信息。文档字符串可以被许多工具自动提取和展示，包括帮助文档和交互式帮助。

下面是一些添加Python函数文档字符串的 实践：

1. 使用三重双引号或三重单引号来编写文档字符串，这表示多行字符串。

def greeting(name):
    """
    This function takes a name as input and returns a personalized greeting message.

    Args:
    name (str): The name of the person to greet.

    Returns:
    str: A personalized greeting message.
    """
    return f"Hello, {name}!"

2. 文档字符串应该包括三个主要组成部分：概述、参数和返回值。

- 概述：概述部分应该简要介绍函数的作用和功能。这将帮助其他开发者更好地理解该函数的用途和在何种情况下使用它。

- 参数：参数部分应该描述函数接受的所有参数及其用途。如果函数没有参数，应该清楚地说明这一点。

- 返回值：返回值应该描述函数返回的类型和值。如果函数没有返回值，也应该清楚地说明这一点。

3. 对于每个参数，应该描述它的类型、名称和用途。如果某些参数是可选的，则应该指出默认值。

def get_average(*grades, weights=None):
    """
    This function calculates the weighted average of a list of grades.

    Args:
    grades (list): A list of numeric grades.
    weights (list, optional): A list of weights for each grade. If not provided, each grade will have the same weight.

    Returns:
    float: The weighted average of the grades.
    """
    if weights is None:
        weights = [1] * len(grades)
    return sum(g * w for g, w in zip(grades, weights)) / sum(weights)

4. 可以使用reStructuredText来格式化和排版文档字符串。reStructuredText是一种轻量级的标记语言，具有丰富的HTML输出和其他工具的支持。

def fibonacci(n):
    """
    Return the nth Fibonacci number.

    :param n: The index of the Fibonacci number to return.
    :type n: int
    :returns: The nth Fibonacci number.
    :rtype: int
    :raises ValueError: If n is negative.
    """
    if n < 0:
        raise ValueError("n must be non-negative")
    if n == 0:
        return 0
    if n == 1:
        return 1
    return fibonacci(n-1) + fibonacci(n-2)

总的来说，良好的文档字符串可以提高代码的可读性、可维护性和可重用性，并使其他开发人员更轻松地理解和使用您的代码。因此，请务必为您的Python函数添加文档字符串，并采用 实践来编写和格式化它们。