iru-php-phpdoc
Audit given PHP file(s)/scope for complete, well-formed PHPDoc — class/interface/trait/enum docblocks, public and protected methods and properties, constants, generics and array shapes (`@template`, `
SKILL.md.claude/skills/iru-php-phpdoc/SKILL.md
GitHubPHP PHPDoc
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. This skill only adds/completes documentation comments — it does not
change behavior, signatures, native type declarations, attributes, or any non-comment code. Test code (tests/,
*Test.php, Pest files, phpunit bootstrap files) is out of scope for documentation requirements — it doesn't need
docblocks added, even if named explicitly — but any docblock a test file already has must be left as-is; never
strip or "clean up" existing comments in test code. It makes no assumptions about this being any particular
repository — discover the project's actual flavor, conventions, and tooling fresh each run.
Step 0 — Detect the project's flavor and environment
Use the same flavor markers as iru-php-code-quality Step 1 (and iru-explore), first match wins:
laravel/framework + artisan → laravel; a root PHP file with a Plugin Name: header → wordpress-plugin;
style.css with Theme Name: and/or theme.json → wordpress-theme; a class that extends Module
(PaymentModule/CarrierModule) in the root <module>.php, config.xml, or prestashop/* packages →
prestashop-module; anything else → library. The flavor decides the documentation convention (Step 2) and
which verification tools apply (Step 5).
Resolve where PHP runs exactly as iru-php-code-quality does (host php preferred; else ddev/Sail/wp-env after
docker info succeeds). Editing comments needs no PHP; only Step 5 does.
Step 1 — Determine scope
- Argument provided (comma-separated paths or globs): resolve each to its
.phpfile(s) viafind/ls. Drop any resolved test file per the definition above — say so in the Step 6 report rather than silently ignoring it. - No argument: default to every non-test
.phpfile touched by uncommitted changes plus commits on the current branch not yet on the base branch, same approach asiru-update-docs:
(determine the base branch viagit status git diff <base-branch>...HEAD --name-only git diff --name-onlygit symbolic-ref refs/remotes/origin/HEADorgit branch -aif unclear; ask the user only if genuinely ambiguous). - Always filter out
vendor/,node_modules/, generated or cached code (bootstrap/cache/,storage/,var/,build/), Blade templates (*.blade.php), and PrestaShop'sindex.phpguard files (theheader('Location: ../')stubsautoindexdrops in every folder). - If the resulting scope is empty, tell the user there is nothing to document and stop.
- What gets documented, per in-scope file (the audit set for Step 3):
- library / laravel / prestashop-module: every class, interface, trait, and enum; their public and protected methods (including constructors), properties (including constructor-promoted ones), and constants; enum cases whose meaning isn't obvious from the name; and top-level functions. PrestaShop requires docblocks on classes, properties, and methods regardless of visibility, so private members are in scope there too.
- wordpress-plugin / -theme: all of the above, plus a file header docblock in every PHP file (theme template
files such as
header.php,single.php, ortemplate-parts/*.phpincluded — they need nothing else), every function (plugins and themes are largely procedural),require/includestatements of other plugin files, and every hook invocation —do_action(),do_action_ref_array(),apply_filters(),apply_filters_ref_array().
Step 2 — Discover this project's actual PHPDoc bar before auditing
Don't assume a fixed convention — discover it from the project itself:
- Check a contributor guide (
CLAUDE.md,AGENTS.md,README,CONTRIBUTING, Laravel Boost guidelines under.ai//.github/) for a stated PHPDoc convention. - PHP_CodeSniffer config (
phpcs.xml(.dist),.phpcs.xml(.dist)):WordPressorWordPress-Docs(the WordPress inline-docs rules, built fromSquiz.Commenting.*andGeneric.Commenting.DocComment— e.g.Squiz.Commenting.FunctionComment.MissingParamTagrequires a@paramfor every parameter, typed or not, and...MissingParamCommenta description on each — verified with WordPressCS 3.4), anySquiz.Commenting.*/PEAR.Commenting.*rules, and Slevomat rules that forbid redundant docs (SlevomatCodingStandard.TypeHints.*TypeHint.UselessAnnotation,SlevomatCodingStandard.Commenting.UselessFunctionDocComment). Note each rule's severity — they decide what Step 5 accepts. - Pint / PHP-CS-Fixer rules that rewrite docblocks:
no_superfluous_phpdoc_tags(in Pint'slaravelpreset and PHP-CS-Fixer's@Symfony/@PhpCsFixersets — removes@param/@return/@vartags that only repeat the native type without adding a description),phpdoc_align,phpdoc_separation,phpdoc_order,phpdoc_summary(summary must end with a period),phpdoc_to_comment,no_empty_phpdoc. Ifpint.jsonenablesPint/phpdoc_type_annotations_only, the project deliberately keeps only@-annotation lines (prose summaries are stripped on the nextpintrun) — then write type annotations only, no summaries. Note Pint'slaravelpreset aligns tags with two spaces (@param array{title: string} $row— verified,phpdoc_align); match it. - PHPStan / Psalm: the level (PHPStan ≥ 6 reports
missingType.iterableValue/missingType.generics— everyarray,iterable, and generic class in a signature then needs a PHPDoc value type), and whethertreatPhpDocTypesAsCertainis turned off (it changes how strongly a narrower PHPDoc type is trusted). - If none of the above give a clear answer, skim 2-3 documented classes/functions near the ones in scope to see
whether the project writes summaries on every method,
@paramfor typed parameters,@throws, etc. — treat that observed practice as the bar, following the stricter of stated vs. observed so the output passes the project's own checks.
Skim a couple of existing, well-documented symbols structurally similar to what's in scope (a model if auditing a model, a hook-heavy class if auditing hooks) to internalize phrasing, tag order, alignment, and whether a blank line separates the summary from tags and tag groups from each other. If the project has nothing to learn from, fall back to the flavor convention below.
library / laravel — PHPStan-typed convention (the docs reference's own guidance):
- One-sentence summary (third person, present tense — "Finds the books…"), optional description paragraph.
- Don't repeat in PHPDoc what a native type already says.
@param string $authornext tostring $authoradds nothing; add a@param/@return/@varonly when it says something the native type can't —list<Book>,array<string, int>,non-empty-array<…>, array shapesarray{title: string, year: int, subtitle?: string},non-empty-string,positive-int,int<1, 5>,class-string<Book>,callable(string): int,Closure(Book): bool,iterable<int, Book>,Collection<int, User>,T|nullfor a generic — or when its description carries meaning (units, accepted values, whatnullmeans). A barearray/iterablein a signature always gets a value type. - Generics:
@template T/@template T of objecton the class or method,@extends Collection<Book>,@implements IteratorAggregate<int, Book>,@use HasFactory<UserFactory>(as the Laravel skeleton does) — only where the type actually is generic. @throwsfor every exception the body throws or deliberately lets propagate from a call (@throws InvalidArgumentException When $author is blank.).- Laravel specifics: relation methods get
@return HasMany<Post, $this>(Larastan's generic relation types);casts()gets@return array<string, string>; Eloquent attributes Larastan already infers from migrations don't need@propertytags unless the project already uses them (e.g. via IDE-helper conventions). - Tool-specific overrides (
@phpstan-param,@phpstan-return,@psalm-…,@phpstan-assert) only where the project already uses them. @deprecatedis carried over verbatim, never added — and note the native#[\Deprecated]attribute is how new code emits a runtime notice; that's a code change, out of scope here.
wordpress-plugin / -theme — WordPress PHP inline documentation standards:
- Summary: one sentence, third-person singular verb, ending in a period. Functions say what they do; filters say what is filtered ("Filters the excerpt length."); actions say when they fire ("Fires after a book is saved.").
@since x.y.zon every function, class, method, property, constant, and hook — the version that introduces the element: the plugin header'sVersion:(orstyle.cssVersion:for themes) when the change is part of the upcoming release; if that's ambiguous (the version wasn't bumped yet and no unreleased changelog entry names the next one), ask the user rather than guessing.@paramfor every parameter, with type and description — WordPress-Docs requires it even when the native type is declared:@param int $post_id Post ID.; mark optional ones "Optional." with the default ("Default 'publish'.");bool/int, notboolean/integer; aligned columns. Array arguments use hash notation, one@typeline per key inside the@param's braces.@returnwith type and description when the function returns something (no@return void).@globalfor globals used. Never add@author;@copyright/@licensebelong only to bundled third-party libraries.- File header: a summary statement with no trailing period, an optional description,
@package <PluginName>(themes:<Theme_Name>with underscores; never@package WordPress), and@since. - Hooks: a docblock on the line immediately before the
do_action()/apply_filters()call (or before the enclosing HTML block / long conditional when the call sits inside one), with summary, optional description,@since, and one@paramper argument passed after the hook name, in order — no@return. phpstan-wordpress validates these (verified against phpstan-wordpress 2.x): its rule reportsparamTag.count("Expected N @param tags, found M."),phpDoc.parseError(a malformed or$this-named@param), andparameter.phpDocType(a@paramtype that doesn't accept the actual argument), and it treats a filter's first@paramtype as the filter's return type. Dynamic hook names ("save_post_{$post->post_type}") are documented the same way with the variable part kept in the name. A hook fired in more than one place is documented fully once; other occurrences get a one-line/** This filter is documented in path/to/file.php */.
prestashop-module — PrestaShop conventions:
- The file must already start with the module's AFL-3.0 license block — that block is maintained by
iru-check-license(orvendor/bin/header-stamp); never edit it here, and place new docblocks after it. - Classes, properties, and methods get docblocks regardless of visibility; describe intent rather than implementation, and document parameters and return values in both type and meaning.
- Arrays:
string[]for simple collections,array<int, string>when keys matter, array shapes for structs with a known schema. Module code that still supports PHP versions without native parameter/return types (checkcomposer.jsonrequire.phpandconfig.xml'sps_versions_compliancy) relies on docblocks for every type — write full@param/@returntags there. - Hook methods (
hookDisplayHeader(array $params), …) document the$paramskeys the hook actually passes. - Deprecations, when already present, keep PrestaShop's
@deprecated Since x.y.z, use …() instead.form.
Step 3 — Audit each in-scope file
Read the full file, then for every symbol in Step 1's audit set check that a /** ... */ docblock exists, sits
directly above the declaration (attributes may sit between docblock and declaration), and actually describes the
symbol's purpose rather than restating its name, per the bar from Step 2:
- Classes, interfaces, traits, enums: a docblock on the type, with
@template/@extends/@implements/@usewhere the type is generic or extends/implements/uses a generic type. - Methods and functions: summary;
@paramwhere the bar requires it (always for WordPress/PrestaShop; for library/laravel only where a native type can't express the real type, or there is no native type at all);@returnlikewise;@throwsfor each exception that can propagate. Check existing tags still match the current signature — a@paramfor a renamed/removed parameter, or in the wrong order, is a gap too. - Properties and constants: a docblock (or a one-line
/** @var list<string> */where only the type needs refining); constructor-promoted properties are documented through the constructor's@param. - Overrides / interface implementations: only document them separately if the project does; otherwise rely on
inherited PHPDoc (PHPStan and phpDocumentor inherit it), or
{@inheritDoc}if that's the project's habit. - WordPress: file header; every hook invocation;
require/includelines get a short/** ... */comment saying what is loaded.
For each gap record: the symbol, its kind, what's missing (whole docblock vs. a missing/stale tag), and the file.
Step 4 — Generate the missing PHPDoc
Before editing, if PHPStan (or Psalm) is wired, run it once on the in-scope files exactly as Step 5 does and keep the per-file results as this run's baseline — Step 5 needs it to tell pre-existing errors from ones the new docs caused.
For every gap from Step 3, write the docblock grounded in:
- The actual implementation — read the body: which array keys are read or written (for a shape), what the list
elements are, which exceptions are thrown or rethrown, what
null/falsereturns mean, which arguments a hook passes. Never invent a narrower type than the code guarantees: a@return list<string>on something that can return an associative array is a lie PHPStan will either reject or, worse, trust. - Current uncommitted/branch changes (
git diff/git log -pfor that file) — describe current behavior, not what the name suggests. - The conventions from Step 2 — voice, tag order, alignment, blank-line layout — so new comments are indistinguishable from hand-written ones.
Apply the edits with the Edit tool. Do not modify code logic, signatures, native types, attributes, the license header, or formatting outside the added/completed comments, and don't reorder members.
Step 5 — Verify
Run what the project has, scoped to the in-scope files, through the environment from Step 0. Write any report under
build/ with an iru-php-phpdoc- prefix and delete it afterwards (remove build/ only if this run created it).
- PHPStan (when wired — config and flags exactly as
iru-php-code-qualityStep 2 runs it, including_PS_ROOT_DIR_for PrestaShop):vendor/bin/phpstan analyse --no-progress --error-format=json [-c <config>] [--memory-limit=1G] <files> > build/iru-php-phpdoc-phpstan.json(pass--memory-limit=1Gwhenever phpstan-wordpress/Larastan/the PrestaShop extension is loaded — verified: with phpstan-wordpress the default 128M crashes the worker and the JSON holds only a top-levelerrorsentry aboutAllowed memory size, i.e. no validation happened). PHPStan validates PHPDoc from level 2 up. Compare against the Step 4 baseline: any new error in an in-scope file was caused by the docblocks, since nothing else changed — typicallyphpDoc.parseError(unparseable type or tag),parameter.phpDocType/return.phpDocType/property.phpDocType(PHPDoc type incompatible with the native type),parameter.notFound(@paramnaming a parameter that doesn't exist),throws.notThrowable/class.notFound(an unimported or misspelled class in a PHPDoc type — import it withuseor fully qualify it),throws.unusedType(a@throwsfor an exception the body never throws),missingType.*,generics.*,paramTag.count(phpstan-wordpress hook docs), or a new error in the body because a narrower PHPDoc type is now trusted (*.alwaysTrue,deadCode.*) — the last one means the docblock overstates the code; widen it. Fix and re-run until no new errors remain. Pre-existing errors are not this skill's to fix. Because narrower types also flow into callers, when the project's PHPStan run is affordable (result cache warm, or a small project) also run it project-wide and report — not fix — any new error outside scope. If the project uses Psalm instead, runvendor/bin/psalm --output-format=json --no-progress <files>the same way (InvalidDocblock,MismatchingDocblockParamType,MismatchingDocblockReturnType,UndefinedDocblockClass). With neither wired, at least runphp -l <file>on each edited file and say in the report that no PHPDoc type validation was available. - PHP_CodeSniffer documentation sniffs (when the config references
WordPress,WordPress-Docs, or any*.Commenting.*rules):vendor/bin/phpcs --report=json --report-file=build/iru-php-phpdoc-phpcs.json -q --basepath=. <files>, then look at messages whosesourcestarts withSquiz.Commenting.,Generic.Commenting.,PEAR.Commenting.,SlevomatCodingStandard.Commenting., or ends in.UselessAnnotation. Fix every one in the comments you wrote. For a WordPress project whose config doesn't include WordPress-Docs but has WordPressCS installed (vendor/bin/phpcs -ilists it), you may additionally run--standard=WordPress-Docson the files as an advisory check — say so, and don't treat its findings as failures the project enforces. - Pint / PHP-CS-Fixer docblock rules (when configured): run the style check on the edited files in dry-run mode
(
vendor/bin/pint --test -v <files> --output-to-file=build/iru-php-phpdoc-pint.json --output-format=json, orvendor/bin/php-cs-fixer check --format=json -v --path-mode=intersection <files>) and adjust the comments you wrote for anyphpdoc_*,no_superfluous_phpdoc_tags,no_empty_phpdoc, orPint/phpdoc_type_annotations_onlyfixer the report lists — by hand, never by running the fixer (it would reformat code beyond the comments). Pre-existing non-docblock style findings are out of scope. - phpDocumentor, only when the project has it — a
phpdoc.dist.xml/phpdoc.xml(aphpdoc.xmltakes precedence overphpdoc.dist.xml),vendor/bin/phpdoc, or a composer script that builds API docs:vendor/bin/phpdoc run [-c <config>] -t build/iru-php-phpdoc-site --cache-folder build/iru-php-phpdoc-cache(when the project runs it from thephpdoc/phpdocDocker image or a downloadedphpDocumentor.phar, use that same invocation with the same output overrides). Writing to a throwaway target keeps the project's real docs output untouched. Treat a non-zero exit or any error-level log line naming an in-scope file (a docblock it couldn't parse, an unresolvable type) as a failure to fix; phpDocumentor also lists parse problems in the generated site's errors report. Delete the throwaway output afterwards.
A failure naming a symbol or file outside the current scope is pre-existing — mention it in the report as a follow-up, don't fix it unless the user asks.
Step 6 — Report
Per file in scope: how many symbols were already fully documented, how many gaps were found and filled (name each,
with its kind and what was added — e.g. "Shelf class: @template T of object", "titlesBy(): @param list<array{...}> $books, @throws InvalidArgumentException",
"apply_filters( 'myplugin_excerpt_length' ): hook docblock with 2 @param"), and for WordPress files whether a
file header was added. Then the verification result per tool that ran — PHPStan/Psalm: no new errors vs. baseline
(or the identifiers still open), phpcs commenting sniffs: pass or the remaining sources, Pint/PHP-CS-Fixer docblock
rules: pass or remaining fixers, phpDocumentor: pass/fail — and which tools weren't available. Name any argument
that resolved to a test file and was excluded, any @since version you had to ask about, and any out-of-scope
pre-existing failures as follow-ups. Never paste raw tool output or JSON.
Do not fix static-analysis or style issues unrelated to docblocks, change code to make a docblock "true", edit license headers, or add/modify tests — those are a separate quality/implementation skill's job.