write-docblocks

Write Docblocks

Overview

Batch-process PHPDoc documentation gaps by running composer docs:coverage:missing and dispatching parallel phpdoc-writer subagents.

Core principle: Process files in batches of 5 subagents for efficient parallel documentation without overwhelming the system.

When to Use

• Documentation coverage below target (80% classes, 75% methods)
• After creating multiple new services, controllers, or models
• When composer docs:coverage:missing shows many files needing docs
• User requests batch PHPDoc writing

Workflow

digraph write_docblocks {
    rankdir=TB;

    start [label="Run composer docs:coverage:missing" shape=box];
    parse [label="Parse output for file paths" shape=box];
    check [label="Files remaining?" shape=diamond];
    batch [label="Take next 5 files" shape=box];
    dispatch [label="Dispatch 5 phpdoc-writer\nsubagents in parallel" shape=box];
    wait [label="Wait for batch to complete" shape=box];
    done [label="Run composer docs:coverage\nto verify improvement" shape=box];

    start -> parse -> check;
    check -> batch [label="yes"];
    check -> done [label="no"];
    batch -> dispatch -> wait -> check;
}

Execution Steps

1. Get Missing Files

composer docs:coverage:missing 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | grep '\.php$'

This strips ANSI codes and extracts just file paths like:

Console/Commands/ProcessDataCommand.php
Http/Controllers/AuthController.php
Services/AuthService.php

2. Process in Batches of 5

For each batch of 5 files, dispatch phpdoc-writer subagents in parallel using a single message with multiple Task tool calls:

Task(subagent_type="phpdoc-writer", prompt="Write PHPDoc blocks for app/Console/Commands/ProcessDataCommand.php - read the file, understand its purpose, and add comprehensive docblocks for the class and all undocumented methods.")

Task(subagent_type="phpdoc-writer", prompt="Write PHPDoc blocks for app/Http/Controllers/OAuthController.php - read the file, understand its purpose, and add comprehensive docblocks for the class and all undocumented methods.")

// ... 3 more in same message