PHP PHPDoc

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Make sure a set of PHP files carry complete, well-formed PHPDoc, filling in whatever is missing, then prove the result is valid through the project’s own tooling. It only adds or completes documentation comments — it never changes behavior, signatures, native types, attributes or non-comment code.

Purpose

iru-php-phpdoc detects the project flavor (Laravel, WordPress plugin or theme, PrestaShop module, or plain library) and applies that flavor’s documentation convention. Libraries and Laravel follow the PHPStan-typed convention of not repeating native types, using @template, array shapes, list<T> and class-string<T> only where they add information. WordPress code follows the WordPress inline documentation standards: file headers, @since, full @param and @return tags, and a hook docblock before every do_action() and apply_filters(). PrestaShop modules get docblocks on classes, properties and methods regardless of visibility (the license header itself is iru-check-license’s job). It discovers the project’s real bar first (phpcs and Pint/PHP-CS-Fixer rules, PHPStan level, contributor guides), generates docblocks grounded in the actual code, then verifies with PHPStan (or Psalm), PHP_CodeSniffer commenting sniffs, Pint/PHP-CS-Fixer `phpdoc_* rules and phpDocumentor, comparing against a baseline taken before the edits. Test code is out of scope for requirements and its existing comments are never stripped.

Purpose group

PHP Development Tooling

Plugin

Shipped by the iru-php plugin of the ai-catalog marketplace (install with /plugin install iru-php@ai-catalog; see Plugins).

Invocation

/iru-php-phpdoc <path-or-glob>
/iru-php-phpdoc

Comma-separated paths or globs are accepted.

Inputs

Argument Required Description Default

Argument	Required	Description	Default
`path-or-glob`	No	One or more files, directories or globs resolving to `.php` files. Test files, `vendor/`, generated or cached code, Blade templates and PrestaShop `index.php` guard stubs are dropped and named in the report.	Non-test `.php` files touched by uncommitted changes plus commits on the current branch not yet on the base branch; an empty scope stops with "nothing to document".

path-or-glob

One or more files, directories or globs resolving to .php files. Test files, vendor/, generated or cached code, Blade templates and PrestaShop index.php guard stubs are dropped and named in the report.

Non-test .php files touched by uncommitted changes plus commits on the current branch not yet on the base branch; an empty scope stops with "nothing to document".

Outputs

Edited .php files with added or completed docblocks (and WordPress file headers where required).
A per-file report: symbols already documented, gaps found and filled (kind and what was added), and whether a file header was added.
The verification result per tool that ran — PHPStan or Psalm (no new errors versus the baseline), phpcs commenting sniffs, Pint/PHP-CS-Fixer docblock rules, phpDocumentor — and which tools were unavailable.
Excluded test arguments, any @since version that had to be asked about, and out-of-scope pre-existing failures as follow-ups. Raw tool output is never pasted.

Execution flow

flowchart TD A["Start /iru-php-phpdoc\n(optional paths)"] --> B["Step 0: Detect flavor\n(laravel, wordpress, prestashop, library)\nand where PHP runs"] B --> C["Step 1: Resolve scope,\ndrop tests, vendor, Blade, index stubs"] C --> D{"Scope empty?"} D -- yes --> E["Report nothing to document and stop"] D -- no --> F["Step 2: Discover the project's PHPDoc bar\n(phpcs, Pint, PHPStan level, guides)"] F --> G["Step 3: Audit each file\nfor missing or stale docblocks"] G --> H["Step 4: Capture PHPStan baseline,\nthen write the missing docblocks"] H --> I["Step 5: Verify with PHPStan or Psalm,\nphpcs, Pint, phpDocumentor"] I --> J{"New errors in\nin-scope files?"} J -- yes --> K["Fix the comments and re-run"] K --> I J -- no --> L["Step 6: Report"]

Dependencies

Invokes

None — iru-php-phpdoc is a leaf skill; it edits comments and runs the project’s own PHPStan, phpcs, Pint and phpDocumentor tooling directly. It reuses iru-php-code-quality’s and `iru-explore’s flavor markers and `iru-update-docs’s scope approach by convention, and defers license headers to `iru-check-license, but calls none of them.

Invoked by

PHP Code One Task Group — Step 3.2, PHPDoc for touched production files, via the iru-gate-runner agent.

Related agents

None — this skill does not spawn agents itself; callers run it inside an iru-gate-runner sub-agent.

Source

SKILL.md on GitHub — the file this page was generated from.