docstring

使用符合项目约定的 Google 风格文档字符串，为 Python 模块或类编写文档。参数可以是类名或模块路径。

说明

1. 根据参数确定要编写文档的对象：

   如果提供了模块路径（例如 src/pipecat/audio/vad/vad_analyzer.py）：

   • 直接使用该文件

   如果提供了类名（例如 VADAnalyzer）：

   • 在 src/pipecat/ 中搜索 class ClassName
   • 如果多个文件中都包含该类名，列出所有匹配项及其文件路径，询问用户要为哪个文件编写文档，并等待确认

2. 确认文件后，阅读模块以了解其结构：

   • 识别所有类、函数和重要的类型别名
   • 了解每个组件的用途

3. 按以下顺序添加文档：

   • 模块文档字符串（位于顶部、导入语句之后）
   • 类文档字符串
   • __init__ 方法（始终为构造函数参数编写文档）
   • 公共方法（名称不以 _ 开头）
   • 带字段说明的数据类／配置类

4. 以下内容无需添加文档：

   • 私有方法（名称以 _ 开头）
   • 简单的特殊方法（__str__、__repr__、__post_init__）
   • 非常简单的透传属性
   • 已有文档的代码——如果类、方法或函数已有完整且符合项目风格的文档字符串，则不要修改。完整的文档字符串应包含：
     • 一行摘要
     • Args 部分（如果有参数）
     • Returns 部分（如果有有意义的返回值）
   • 只为缺少文档或文档不完整的内容添加或完善文档

模块文档字符串格式

"""[One-line description of module purpose].

[Optional: Longer explanation of functionality, key classes, or use cases.]
"""

示例：

"""Neuphonic text-to-speech service implementations.

This module provides WebSocket and HTTP-based integrations with Neuphonic's
text-to-speech API for real-time audio synthesis.
"""

类文档字符串格式

class ClassName:
    """One-line summary describing what the class does.

    [Longer description explaining purpose, behavior, and key features.
    Use action-oriented language.]

    [Optional: Event handlers, usage notes, or important caveats.]
    """

示例：

class FrameProcessor(BaseObject):
    """Base class for all frame processors in the pipeline.

    Frame processors are the building blocks of Pipecat pipelines, they can be
    linked to form complex processing pipelines. They receive frames, process
    them, and pass them to the next or previous processor in the chain.

    Event handlers available:

    - on_before_process_frame: Called before a frame is processed
    - on_after_process_frame: Called after a frame is processed

    Example::

        @processor.event_handler("on_before_process_frame")
        async def on_before_process_frame(processor, frame):
            ...

        @processor.event_handler("on_after_process_frame")
        async def on_after_process_frame(processor, frame):
            ...
    """

注意：列出事件处理程序时，不要使用反引号。请包含 Example:: 部分（带两个冒号，供 Sphinx 使用），展示装饰器模式以及每个事件对应的函数签名。

构造函数（__init__）格式

def __init__(self, *, param1: Type, param2: Type = default, **kwargs):
    """Initialize the [ClassName].

    Args:
        param1: Description of param1 and its purpose.
        param2: Description of param2. Defaults to [default].
        **kwargs: Additional arguments passed to parent class.
    """

示例：

def __init__(
    self,
    *,
    api_key: str,
    voice_id: Optional[str] = None,
    sample_rate: Optional[int] = 22050,
    **kwargs,
):
    """Initialize the Neuphonic TTS service.

    Args:
        api_key: Neuphonic API key for authentication.
        voice_id: ID of the voice to use for synthesis.
        sample_rate: Audio sample rate in Hz. Defaults to 22050.
        **kwargs: Additional arguments passed to parent InterruptibleTTSService.
    """

方法文档字符串格式

async def method_name(self, param1: Type) -> ReturnType:
    """One-line summary of what method does.

    [Longer description if behavior isn't obvious.]

    Args:
        param1: Description of param1.

    Returns:
        Description of return value.

    Raises:
        ExceptionType: When this exception is raised.
    """

示例：

async def put(self, item: Tuple[Frame, FrameDirection, FrameCallback]):
    """Put an item into the priority queue.

    System frames (`SystemFrame`) have higher priority than any other
    frames. If a non-frame item is provided it will have the highest priority.

    Args:
        item: The item to enqueue.
    """

数据类／配置格式

@dataclass
class ConfigName:
    """One-line description of configuration.

    [Explanation of when/how to use this config.]

    Parameters:
        field1: Description of field1.
        field2: Description of field2. Defaults to [default].
    """

    field1: Type
    field2: Type = default_value

示例：

@dataclass
class FrameProcessorSetup:
    """Configuration parameters for frame processor initialization.

    Parameters:
        clock: The clock instance for timing operations.
        task_manager: The task manager for handling async operations.
        observer: Optional observer for monitoring frame processing events.
    """

    clock: BaseClock
    task_manager: BaseTaskManager
    observer: Optional[BaseObserver] = None

枚举文档格式

class EnumName(Enum):
    """One-line description of the enum purpose.

    [Longer description of how the enum is used.]

    Parameters:
        VALUE1: Description of VALUE1.
        VALUE2: Description of VALUE2.
    """

    VALUE1 = 1
    VALUE2 = 2

写作风格指南

• 简洁、专业——不使用随意的语言或填充词
• 以行动为导向——以动词开头，例如：“处理……”“管理……”“转换……”
• 目的优先于实现——先说明原因，再说明方式
• 清楚说明参数——包含类型提示、默认值和用途
• 避免重复类型信息——类型提示已在签名中给出，无需在说明中重复
• 使用反引号标记代码引用——将类名、方法名、事件名、参数名和代码片段括在反引号中

正确：“用于身份验证的 Neuphonic API 密钥。” 错误：“str：用于向 Neuphonic 进行身份验证的 API 密钥（字符串）。”

正确：“VADAnalyzer 检测到语音时触发 on_speech_started。” 错误：“VADAnalyzer 检测到语音时触发 on_speech_started。”

弃用通知格式

为已弃用的代码编写文档时：

"""[Description].

.. deprecated:: X.X.X
    `ClassName` is deprecated and will be removed in a future version.
    Use `NewClassName` instead.
"""

检查清单

完成前，对已编写文档的文件运行 /prose-review <path> 并修复其标记的所有问题，然后确认：

• 模块在顶部（版权声明和导入语句之后）包含文档字符串
• 所有公共类都包含文档字符串
• 所有 __init__ 方法都说明了参数
• 所有公共方法都按需包含 Args／Returns／Raises
• 数据类使用 “Parameters:” 部分说明字段
• 枚举在 “Parameters:” 部分说明每个值
• 写作简洁且以行动为导向
• 未为私有方法（名称以 _ 开头）添加文档
• 保持现有完整文档字符串不变