Fix PHPDoc inconsistencies and remove duplicate code

[galatanovidiu]

Why

The v0.5.0 code review found 8 documentation and annotation issues: inconsistent @since tags, placeholder URLs left from scaffolding, a missing PHPDoc block, duplicated logic, and a missing @internal annotation. None of these affect runtime behavior.

What

PHPDoc fixes:

• Fix @since n.e.x.t. trailing periods in 4 files (6 occurrences) — standardize to @since n.e.x.t
• Add missing PHPDoc block to McpServer::get_error_handler() — the only getter without one
• Add @since 0.1.0 to wp_mcp_init action in Plugin.php — the only hook missing a @since tag
• Fix @since/@param ordering on 3 hooks (mcp_adapter_tool_name, mcp_adapter_resource_uri, mcp_adapter_resource_name) — @since before @param per WordPress PHPDoc standards

Annotation fixes:

• Fix placeholder @see URLs in 3 Ability classes — your-repo → WordPress
• Add @internal annotation to HttpRequestHandler — clarifies it is not part of the public API

Dead code removal:

• Remove duplicate categorize_error() from RequestRouter — use McpObservabilityHelperTrait::categorize_error() instead (identical logic, one source of truth)

Test plan

• No behavioral changes — all fixes are PHPDoc, annotations, or dead code removal
• Full suite: 975 tests, 3772 assertions, 0 failures
• PHPStan Level 8: 0 errors
• PHPCS: 0 violations

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: galatanovidiu <ovidiu-galatan@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.74%. Comparing base (1111068) to head (0e4d716).
⚠️ Report is 2 commits behind head on trunk.

Additional details and impacted files

@@            Coverage Diff            @@
##              trunk     #155   +/-   ##
=========================================
  Coverage     87.74%   87.74%           
  Complexity     1230     1230           
=========================================
  Files            54       54           
  Lines          3990     3990           
=========================================
  Hits           3501     3501           
  Misses          489      489           

Flag	Coverage Δ
unit	87.74% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This PR focuses on cleanup work discovered during the v0.5.0 review: standardizing PHPDoc (@since formatting and ordering), improving annotations/docs links, clarifying internal API surface, and removing duplicate error-categorization logic in favor of a shared helper.

Changes:

• Standardize @since n.e.x.t formatting (remove trailing periods) and reorder hook PHPDoc to match WordPress standards.
• Add missing PHPDoc blocks/annotations (McpServer::get_error_handler(), wp_mcp_init hook @since, @internal on HttpRequestHandler).
• Remove duplicated categorize_error() from RequestRouter and route categorization through McpObservabilityHelperTrait.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
includes/Transport/Infrastructure/RequestRouter.php	Removes duplicated categorize_error() and switches to shared helper for error category tagging.
includes/Transport/Infrastructure/HttpRequestHandler.php	Adds @internal and fixes @since formatting.
includes/Transport/Infrastructure/HttpRequestContext.php	Fixes @since formatting.
includes/Plugin.php	Adds @since tag to wp_mcp_init action PHPDoc.
includes/Handlers/Initialize/InitializeHandler.php	Fixes @since formatting.
includes/Domain/Tools/RegisterAbilityAsMcpTool.php	Reorders filter PHPDoc so @since precedes @param.
includes/Domain/Resources/RegisterAbilityAsMcpResource.php	Reorders filter PHPDoc so @since precedes @param (two hooks).
includes/Core/McpVersionNegotiator.php	Fixes @since formatting in class/method PHPDoc.
includes/Core/McpServer.php	Adds missing PHPDoc block to get_error_handler().
includes/Abilities/GetAbilityInfoAbility.php	Replaces placeholder @see URL.
includes/Abilities/ExecuteAbilityAbility.php	Replaces placeholder @see URL.
includes/Abilities/DiscoverAbilitiesAbility.php	Replaces placeholder @see URL.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.