Move new annotations property under meta and update docs

[gziolo]

Follow-up #99.

Addresses the feedback from #106.

Branch is currently based on #107 to minimize the need for merge conflict resolution. Both PRs move properties to meta, so similar lines need to be updated.

Refactoring ensures that annotations is no longer a top-level property in the WP_Ability class. Instead, it is now its group inside the meta property. This is similar to the previous changes applied to the show_in_rest property. As part of the refactoring get_annotations() public method got removed in favor of get_meta_item( 'annotation' ) calls.

This PR expands on the documentation change necessary for understanding how the annotation property inside meta property on WP_Ability should be used.

[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: gziolo <[email protected]>
Co-authored-by: JasonTheAdams <[email protected]>

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

[Copilot]

Pull Request Overview

This PR expands documentation for the new annotations property on WP_Ability objects, providing comprehensive details about its structure and usage across multiple documentation files.

• Added detailed documentation for the annotations property structure and its four supported keys
• Included practical examples showing how to use annotations in ability registration
• Updated REST API documentation to show the annotations property in JSON responses

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
docs/3.registering-abilities.md	Added detailed documentation for the annotations parameter and updated code examples to demonstrate usage
docs/4.using-abilities.md	Added example code showing how to retrieve annotations from an ability object
docs/5.rest-api.md	Updated JSON response examples to include the annotations property structure

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.24%. Comparing base (124d8be) to head (b2f6518).
⚠️ Report is 1 commits behind head on trunk.

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk     #104      +/-   ##
============================================
- Coverage     86.27%   86.24%   -0.04%     
+ Complexity      111      110       -1     
============================================
  Files            16       16              
  Lines           809      807       -2     
  Branches         85       85              
============================================
- Hits            698      696       -2     
  Misses          111      111              

Flag	Coverage Δ
javascript	92.62% <100.00%> (ø)
unit	83.89% <100.00%> (-0.06%)	⬇️

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.

[JasonTheAdams]

As a quick note, I want to make sure that we're documenting the decision elsewhere that all annotations should be snake case.

[gziolo]

Sure, snake case usage is a coding style convention in WordPress and we discussed that yesterday with shared understanding it’s not always convenient. I will link later to the thread.

[gziolo]

Depends now on #106.

[gziolo]

I temporarily based this PR on #107, and extended its scope based on the feedback from #106.

[Copilot]

Pull Request Overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[JasonTheAdams]

Thanks for doing this, @gziolo! I left one question, but for me it's not a blocker to merging, so I'll go ahead and approve!

[JasonTheAdams]

What is the typical WordPress approach to redundancy? I personally wouldn't mind having a getter and setter for annotations, while still storing them in meta. Yes, one could use get_meta() to retrieve the annotations, but for built-in meta it's nice to have more declarative methods.

[gziolo]

I’m very much open for adding a getter to simplify access to individual annotations. I don’t think WordPress core has many good reference points in that regard because older code is often composed of functions chained together. I can spin a follow up PR. To confirm we are on the same page, are we talking about something like:

$this->get_annotation( ‘readonly’ );

[JasonTheAdams]

Yup! Exactly. Just convenience methods.

[justlevine]

If possible, I'd like to save convenience methods for 7.0.

I know nested arrays are messy so I see why we might want to make an exception for annotations (at least in their current shape), but FWIW @gziolo did just introduce ::get_meta_item() in #107, so the method would only be at the convenience of $ability->get_meta_item( 'annotations' )['readonly']

[JasonTheAdams]

I don't see a reason to hesitate on these things unless you foresee something like annotations going away or moving.

[justlevine]

@JasonTheAdams more details in the comment and subsequent discussion I linked to above in #62 but tl;dr I expect at minimum "annotation" to be renamed to something that makes sense semanticaly in non-MCP contexts, as well as the shape/location/keys for some of the meta based on what gets decided in #106 . Hopefully in time for 6.9 so it too doesn't become cumulative tech debt.

But also if I couldn't think of ways to possibly improve the semantics/dx, I'd hope the fact that we're not dogfooding the function internally would be reason enough to pause. We're already navelgazing these props into existence, it's counterproductive to keep expanding our API with compounding layers of conjecture, and slows down our ability to iterate since once something is in core we need to work around it forever.

(Like the linked comment it's not a big deal if we add it now in time for beta1 and then remove during core review. But I do feel it's pretty likely this method will be obviated before rc )