Python中docstring(文档字符串)用法示例详解

目录

• 基本用法
• 1. 函数文档字符串
• 2. 类文档字符串
• 查看文档字符串
• 1. 使用help()函数
• 2. 使用__doc__属性
• 3. 在交互式环境中
• 常见的文档字符串格式
• 1. Google风格
• 2. NumPy风格
• 模块级别的文档字符串
• 实际示例
• 总结

在Python中，docstring（文档字符串）是用来为模块、类、方法、函数等提供文档的一种方式。它是一个字符串字面量，出现在模块、类、函数或方法的定义的第一条语句。通过使用docstring，我们可以为代码添加描述性的文档，这些文档可以通过内置的help()函数或者各种文档生成工具（如Sphinx）来查看。

下面是一个简单的例子，展示如何在函数中使用docstring：

def add(a, b):
    """
    计算两个数的和

    参数:
    a (int): 第一个加数
    b (int): 第二个加数

    返回:
    int: 两个加数的和
    """
    return a + b

然后，我们可以通过以下方式查看这个函数的文档：

1. 使用help()函数：在Python交互环境中，输入help(add)，就会显示这个函数的文档字符串。

2. 使用__doc__属性：直接打印add.doc，也会输出同样的文档字符串。

例如：

print(help(add))
# 或者
print(add.__doc__)

docstring的格式可以有很多种，常见的包括纯文本、reStructuredText（reST）和Google风格等。上面例子中使用的是比较常见的格式，类似于Google风格。

使用docstring的好处是：

• 代码和文档在一起，容易维护。

• 可以通过工具自动生成文档。

• 方便其他开发者理解你的代码。

在编写大型项目时，良好的docstring是非常重要的。

在Python中，docstring（文档字符串）是一种特殊的字符串，用于为模块、函数、类和方法提供文档说明。它位于定义的第一行，用三个双引号 """ 或三个单引号 ''' 包裹。

def add(a, b):
    """
    计算两个数的和
    
    参数:
    a (int): 第一个数字
    b (int): 第二个数字
    
    返回:
    int: 两个数字的和
    
    示例:
    >>> add(2, 3)
    5
    >>> add(-1, 1)
    0
    """
    return a + b

class Calculator:
    """
    一个简单的计算器类
    
    属性:
    brand (str): 计算器品牌
    
    方法:
    add: 加法运算
    subtract: 减法运算
    """
    
    def __init__(self, brand):
        self.brand = brand
    
    def multiply(self, a, b):
        """返回两个数的乘积"""
        return a * b

help(add)
# 或者
help(Calculator)

print(add.__doc__)
print(Calculator.__doc__)

# 在IPython或Jupyter中
add?
# 或者
add??

def calculate_area(radius):
    """
    计算圆的面积
    
    Args:
        radius (float): 圆的半径
        
    Returns:
        float: 圆的面积
        
    Raises:
        ValueError: 当半径为负数时
        
    Example:
        >>> calculate_area(5)
        78.53981633974483
    """
    if radius < 0:
        raise ValueError("半径不能为负数")
    return 3.141592653589793 * radius ** 2

def calculate_area(radius):
    """
    计算圆的面积
    
    Parameters
    ----------
    radius : float
        圆的半径
        
    Returns
    -------
    float
        圆的面积
        
    Examples
    --------
    >>> calculate_area(5)
    78.53981633974483
    """
    return 3.141592653589793 * radius ** 2

"""
math_utils.py

这个模块提供了一些数学工具函数。

包含的功能:
- 基本算术运算
- 几何计算
- 统计函数

作者: Your Name
版本: 1.0
"""

def average(numbers):
    """计算数字列表的平均值"""
    return sum(numbers) / len(numbers)

class BankAccount:
    """
    银行账户类
    
    属性:
        account_holder (str): 账户持有人姓名
        balance (float): 账户余额
        account_number (str): 账户号码
        
    方法:
        deposit: 存款
        withdraw: 取款
        get_balance: 查询余额
    """
    
    def __init__(self, account_holder, initial_balance=0):
        """
        初始化银行账户
        
        Args:
            account_holder (str): 账户持有人姓名
            initial_balance (float, optional): 初始余额，默认为0
        """
        self.account_holder = account_holder
        self.balance = initial_balance
        self.account_number = self._generate_account_number()
    
    def deposit(self, amount):
        """
        存款操作
        
        Args:
            amount (float): 存款金额
            
        Returns:
            float: 更新后的余额
            
        Raises:
            ValueError: 当存款金额为负数时
        """
        if amount <= 0:
            raise ValueError("存款金额必须为正数")
        self.balance += amount
        return self.balance
    
    def withdraw(self, amount):
        """
        取款操作
        
        Args:
            amount (float): 取款金额
            
        Returns:
            float: 更新后的余额
            
        Raises:
            ValueError: 当取款金额为负数或超过余额时
        """
        if amount <= 0:
            raise ValueError("取款金额必须为正数")
        if amount > self.balance:
            raise ValueError("余额不足")
        self.balance -= amount
        return self.balance

# 使用帮助文档
help(BankAccount)
help(BankAccount.deposit)

通过docstring添加帮助文档的主要好处：

1. 自我文档化：代码和文档在一起，便于维护
2. 交互式帮助：在Python解释器中可以直接查看
3. 自动化文档：可以被Sphinx等工具自动提取生成API文档
4. 代码可读性：让其他开发者更容易理解你的代码
5. IDE支持：大多数IDE可以显示docstring作为提示

这是Python生态系统中的一个重要约定，强烈建议为所有公共接口添加适当的docstring。

到此这篇关于Python中docstring(文档字符串)用法示例详解的文章就介绍到这了,更多相关Python docstring用法内容请搜索风君子博客以前的文章或继续浏览下面的相关文章希望大家以后多多支持风君子博客！

您可能感兴趣的文章:

• python访问类中docstring注释的实现方法
• Python中不可忽视的docstring妙用