Repository navigation
docs(php): document every function and remove the blanket doc-comment suppressions - #178
Merged
Merged
Conversation
… suppressions 116 files under includes/ disabled Squiz.Commenting.FunctionComment, Generic.Commenting.DocComment.MissingShort, and FunctionCommentThrowTag at the top of the file, which hid 1,378 findings: 401 functions with no doc comment, 567 missing @PARAM tags, and tags that no longer matched their signatures. Every one of those disables is removed and the code is now documented instead: - Each function has a summary describing what it does, and a complete, ordered @PARAM list with the signature's types (keeping the existing PHPStan generic types) and a description. - Interface implementations use {@inheritdoc}, so each port documents its contract once; phpcs.xml.dist enables Squiz's skipIfInheritdoc for them. - Every exception a function throws has a @throws tag. - Typed callable and Closure signatures move to @phpstan-param, which Squiz's type-hint check cannot parse. Database_Values::decode_json() now reports malformed JSON as the InvalidArgumentException it already documented, with the JsonException as the previous exception, instead of leaking an undeclared exception type; the three repository hydrators that caught both now catch the one. Database-boundary disables are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
TheAggressive
added a commit
that referenced
this pull request
Oct 11, 2026
… suppressions (#178) 116 files under includes/ disabled Squiz.Commenting.FunctionComment, Generic.Commenting.DocComment.MissingShort, and FunctionCommentThrowTag at the top of the file, which hid 1,378 findings: 401 functions with no doc comment, 567 missing @PARAM tags, and tags that no longer matched their signatures. Every one of those disables is removed and the code is now documented instead: - Each function has a summary describing what it does, and a complete, ordered @PARAM list with the signature's types (keeping the existing PHPStan generic types) and a description. - Interface implementations use {@inheritdoc}, so each port documents its contract once; phpcs.xml.dist enables Squiz's skipIfInheritdoc for them. - Every exception a function throws has a @throws tag. - Typed callable and Closure signatures move to @phpstan-param, which Squiz's type-hint check cannot parse. Database_Values::decode_json() now reports malformed JSON as the InvalidArgumentException it already documented, with the JsonException as the previous exception, instead of leaking an undeclared exception type; the three repository hydrators that caught both now catch the one. Database-boundary disables are unchanged. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
TheAggressive
added a commit
that referenced
this pull request
Oct 11, 2026
* feat(jobs): per-campaign and per-remote-operation locks
Two workers, or a worker and an operator, can no longer act on the same
campaign or the same provider list at once.
- Schema 8 adds {prefix}campaignbridge_locks. Acquiring inserts the name,
so the primary key admits one holder; taking over an expired lock is a
conditional update with one winner; only the holder can release.
- Lock_Manager holds the lock for a whole operation, provider calls
included, and releases it in finally. A caller that finds it held does
nothing and gets the new `locked` workflow error (REST 409) with
retry_after, the seconds until the lock expires. A lock left by a process
that stopped expires after five minutes and the takeover is audited.
- Draft handoff, test send, schedule, unschedule, send, and reconcile hold
the campaign lock; a discovery refresh holds a lock per account and list
and, when one is already running, returns the cached list with a
retryable refusal instead of calling the provider again.
- The campaign timeline labels a takeover "Recovered an interrupted
operation" with the operation that stopped.
Verified on MySQL and on the Studio SQLite site.
Closes #169
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(php): document every function and remove the blanket doc-comment suppressions (#178)
116 files under includes/ disabled Squiz.Commenting.FunctionComment,
Generic.Commenting.DocComment.MissingShort, and FunctionCommentThrowTag at
the top of the file, which hid 1,378 findings: 401 functions with no doc
comment, 567 missing @PARAM tags, and tags that no longer matched their
signatures. Every one of those disables is removed and the code is now
documented instead:
- Each function has a summary describing what it does, and a complete,
ordered @PARAM list with the signature's types (keeping the existing
PHPStan generic types) and a description.
- Interface implementations use {@inheritdoc}, so each port documents its
contract once; phpcs.xml.dist enables Squiz's skipIfInheritdoc for them.
- Every exception a function throws has a @throws tag.
- Typed callable and Closure signatures move to @phpstan-param, which
Squiz's type-hint check cannot parse.
Database_Values::decode_json() now reports malformed JSON as the
InvalidArgumentException it already documented, with the JsonException as
the previous exception, instead of leaking an undeclared exception type;
the three repository hydrators that caught both now catch the one.
Database-boundary disables are unchanged.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #177, which is stacked on #176. The diff here shows only the documentation pass. GitHub retargets the PR as the PRs below it merge.
Why
116 files under
includes/started with// phpcs:disable Squiz.Commenting.FunctionComment,Generic.Commenting.DocComment.MissingShort(often withFunctionCommentThrowTagtoo). That hid 1,378 findings:@paramtags@paramtags out of step with their signatures (wrong name or type)@throwsWhat changed
includes/with the doc sniffs active. The database-boundary disables are unchanged; they're deliberate and documented.@paramlists with the signature's types. Existing PHPStan generic types such asarray<string, mixed>are kept. Descriptions are reused where they already existed, and written in the project's own vocabulary otherwise. Context-sensitive names get context-specific descriptions: for example, an audit$resultversus aCompile_Result, or a job$stateversus a campaign$state.{@inheritDoc}, so each port (*_Source, provider gateways) documents its contract once.phpcs.xml.distenables Squiz'sskipIfInheritdocfor these.@throwson every function that throws.callable(...)and\Closure(...)signatures move to@phpstan-param, because Squiz's type-hint check can't parse them.One behaviour-preserving code change
Once its documentation was accurate,
Database_Values::decode_json()turned out to leak an undeclared\JsonException. It now reports malformed JSON as the\InvalidArgumentExceptionit already documented, with theJsonExceptionattached as the previous exception. The three repository hydrators that caught both types now catch the one. A malformed stored row still reads asnull;Campaign_Operation_Repository_Testcovers this with a{brokencontext row.Verification
pnpm qa:fastpasses, including PHPCS overincludes/,src/,campaignbridge.php, anduninstall.php.🤖 Generated with Claude Code