docstring

Google 形式の docstring を使用し、プロジェクトの規約に従って Python モジュールまたはクラスをドキュメント化します。引数にはクラス名またはモジュールパスを指定できます。

手順

1. 引数に基づいてドキュメント化する対象を決定します。

   モジュールパスが指定された場合（例：src/pipecat/audio/vad/vad_analyzer.py）：

   • そのファイルを直接使用します。

   クラス名が指定された場合（例：VADAnalyzer）：

   • src/pipecat/ 内で class ClassName を検索します。
   • 複数のファイルにそのクラス名がある場合は、ファイルパスとともにすべての該当箇所を一覧表示し、どれをドキュメント化するかユーザーに尋ねて、確認を待ちます。

2. ファイルが特定できたら、モジュールを読み、構造を把握します。

   • すべてのクラス、関数、重要な型エイリアスを特定します。
   • 各コンポーネントの目的を理解します。

3. 次の順序でドキュメントを適用します。

   • モジュール docstring（インポートの後、ファイルの先頭）
   • クラス docstring
   • __init__ メソッド（コンストラクターのパラメーターは必ずドキュメント化）
   • 公開メソッド（_ で始まらないもの）
   • データクラス／設定クラスのフィールド説明

4. 次の項目はドキュメント化を省略します。

   • プライベートメソッド（_ で始まるもの）
   • 単純な dunder メソッド（__str__、__repr__、__post_init__）
   • 非常に単純な、処理をそのまま渡すだけのプロパティ
   • すでにドキュメント化されているコード — クラス、メソッド、関数にプロジェクトのスタイルに沿った完全な docstring がすでにある場合は、変更しないでください。docstring が完全である条件は次のとおりです。
     • 1 行の概要がある
     • パラメーターがある場合は Args セクションがある
     • 意味のある値を返す場合は Returns セクションがある
   • ドキュメントがない箇所、または不完全な箇所にのみ追加・改善します。

モジュール docstring の形式

"""[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.
"""

クラス docstring の形式

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.
    """

メソッド docstring の形式

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

Enum のドキュメント形式

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> を実行し、指摘された内容を修正してから、次の項目を確認します。

• モジュールの先頭（著作権表示とインポートの後）に docstring がある
• すべての公開クラスに docstring がある
• すべての __init__ メソッドでパラメーターが説明されている
• すべての公開メソッドに、必要に応じて Args／Returns／Raises を含む docstring がある
• データクラスではフィールドの説明に Parameters: セクションを使用している
• Enum では各値の説明に Parameters: セクションを使用している
• 簡潔で、動作が明確な文章になっている
• プライベートメソッド（_ で始まるもの）にドキュメントを追加していない
• 既存の完全な docstring を変更していない