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

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

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

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

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

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)