docs: reduce inline comments to why-only; move rationale into doc/#589
Merged
Conversation
…doc/ Comments-only change — no lines of code are touched (verified by comparing php -w output and espree token streams for every file against the previous commit). - PHPDoc/JSDoc blocks now carry a 1-line summary, with a secondary description (max 2 lines) only where the behaviour is genuinely non-obvious. All @since/@param/@return/@var tags are preserved. - Inline what-comments are removed; why-comments are kept and trimmed to 1-2 lines. - Functional comments are untouched (phpcs:ignore, translators, eslint globals, WP dependency headers, plugin header). - Long-form rationale that was worth keeping now lives in doc/: rest-meta-visibility.md, video-settings-payload.md, preselect-generate-audio.md, settings-internals.md, plus additions to wordpress-vip.md — all linked from the README doc index. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Same rules as the src pass; @test/@covers/@group/@dataProvider annotations and Cypress spec-discovery headers are untouched. Flaky-test lore moved to doc/running-tests.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…t in Conflicts in src/post/class-sync.php resolved by keeping main's code (the new BULK_GENERATE_SYNC_LIMIT const and @param tags) with this branch's trimmed prose. The docblocks/inline comments main's bulk-generate change added to Sync, BulkEdit, Notices and their tests are trimmed to the same why-only style. Post-merge, every PHP/JS file in the tree is code-identical to origin/main (php -w / espree token comparison). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
galbus
marked this pull request as ready for review
July 19, 2026 11:02
✅ WordPress Plugin Check Report
📊 ReportAll checks passed! No errors or warnings found. 🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check |
…ht in Conflicts resolved by taking main's code (the poll-based embed replaced the direct player construction) with this branch's why-only comment style. The new lib/poll-content-status.js and the polling additions to the classic metabox, play-audio hooks and their tests are trimmed the same way. Post- merge, every PHP/JS file is code-identical to origin/main (php -w / espree token comparison); phpcs and eslint pass. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
gouravkhunger
approved these changes
Jul 19, 2026
gouravkhunger
left a comment
gouravkhunger
left a comment
Contributor
There was a problem hiding this comment.
Thanks @galbus! It'd be good to get rid of deprecated planning docs too. Anything that's required can be checked if needing any updates to content.
galbus
added a commit
that referenced
this pull request
Jul 19, 2026
main's comment trim (#589) touched the same voice-picker comments this branch had already trimmed, so every conflict was doc-only text around code only this branch has. Resolved by keeping this branch's code throughout — main's side of those hunks is the pre-PR implementation (single Language dropdown, no Native filter, isResolvingVoices) and would have dropped the feature. For the comment text, took whichever side was briefer and still accurate for this branch's code, and corrected the few of main's that described the old single-dropdown behaviour.
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
2 participants
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.
What
Drastically reduces the volume of inline comments and docblock prose across the plugin —
src/, root PHP files,scripts/,tests/phpunit/andtests/cypress/— per the "code explains what, comments explain why" rule:@since/@param/@return/@vartags preserved with their existing values.phpcs:ignore/disable/enable,/* translators: */, eslint globals/disables, WordPress dependency section headers, the plugin header inspeechkit.php, PHPUnit@test/@covers/@group/@dataProviderannotations, and Cypress@group/@coversspec-discovery headers.apply_filters/do_action) kept as public API docs, descriptions trimmed to 1 line.Long-form rationale worth keeping has moved to
doc/and is linked from the README documentation index:doc/rest-meta-visibility.md— how BeyondWords post meta is exposed/hidden over RESTdoc/video-settings-payload.md— why a fullvideo_settingsobject is sent to the content endpointdoc/preselect-generate-audio.md— stored format, legacy shapes, no-dirty editor derivation, save-time decisiondoc/settings-internals.md— settings-error transport, API connection check contractdoc/wordpress-vip.md— new object-cache notes sectiondoc/running-tests.md— new PHPUnit/flaky-test lore sectionsasync-rest-migration.mdandlegacy-meta-migration.mdNo lines of code changed
Every one of the 139 changed PHP/JS files is code-identical to
main: byte-identicalphp -woutput (comments + whitespace stripped) for PHP, identical espree token streams (JSX-aware, comments excluded) for JS. Formatting around removals was also checked — no introduced trailing whitespace, double blank lines, or blank lines adjacent to braces (pattern counts compared per-file againstmain).phpcs(WordPress-VIP-Go ruleset) andwp-scripts lint-jsboth pass.Includes latest
mainorigin/mainis merged in (including the bulk-generate cap from #573). The verbose docblocks/inline comments that feature added toSync,BulkEdit,Noticesand their tests were trimmed to the same style during the merge; conflict resolution kept main's code (new const +@paramtags) with this branch's trimmed prose.147 files changed, +1,027 / −2,694 (net −1,667; additions are almost entirely the new
doc/pages).🤖 Generated with Claude Code