Abilities API: Improve inline documentation for public methods #10412

gziolo · 2025-10-24T11:33:52Z

Trac ticket: https://core.trac.wordpress.org/ticket/64134

Enhances developer experience with comprehensive file header covering API overview, step-by-step usage guide, and best practices. Expands function PHPDocs with practical code examples, detailed parameter descriptions, and cross-references between related functions. Standardizes formatting and improves consistency throughout.

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

github-actions · 2025-10-24T11:34:12Z

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.

Core Committers: Use this line as a base for the props when committing in SVN:

Props gziolo, mukesh27, jason_the_adams, westonruter.

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 enhances the inline documentation for the Abilities API by adding comprehensive file header documentation and improving PHPDoc blocks for all public functions. The changes provide developers with detailed guidance on API usage, including naming conventions, schema definitions, callbacks, REST API integration, and best practices.

Key changes:

Added extensive file header documentation with overview, usage guide, and examples
Enhanced all function PHPDocs with detailed descriptions, practical code examples, and improved parameter documentation
Added cross-references between related functions

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

src/wp-includes/abilities-api.php

github-actions · 2025-10-24T11:52:26Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

mukeshpanchal27 · 2025-10-24T16:45:37Z

src/wp-includes/abilities-api.php

- * @return WP_Ability|null The unregistered ability instance on success, null on failure.
+ * @param string $name The name of the ability to unregister, including namespace prefix
+ *                     (e.g., 'my-plugin/my-ability').
+ * @return WP_Ability|null The unregistered ability instance on success, `null` on failure.


Suggested change

* @return WP_Ability|null The unregistered ability instance on success, `null` on failure.

* @return WP_Ability|null The unregistered ability instance on success, null on failure.

Nit-pick

Can you explain why you suggest to remove markdown formatting here?

For the consistency as WP docs use null on failure in it's docs.

I found multiple places in the code when null is wrapped with backticks, example:

wordpress-develop/src/wp-includes/html-api/class-wp-html-processor.php

Lines 960 to 963 in 70ca20b

* @return bool|null Whether to expect a closer for the currently-matched node,

* or `null` if not matched on any token.

*/

public function expects_closer( ?WP_HTML_Token $node = null ): ?bool {

This is how it looks in the developer docs:

https://developer.wordpress.org/reference/classes/wp_html_processor/expects_closer/#return

I personally prefer it highlighted this way.

JasonTheAdams

Good docs! A couple small suggestions.

src/wp-includes/abilities-api.php

westonruter

Adding a couple suggestions for issues that Gemini helped identify.

src/wp-includes/abilities-api.php

This was discussed in #9410 and decided to defer until after beta1. Fleshing out the phpdocs for the extender functions in https://core.trac.wordpress.org/browser/trunk/src/wp-includes/abilities-api.php should make it easier for people working with the abilities API Developed in #10412. Follw-up [61032]. Props jorbin, gziolo, mukesh27, jason_the_adams, westonruter. Fixes #64134. git-svn-id: https://develop.svn.wordpress.org/trunk@61067 602fd350-edb4-49c9-b593-d223f7449a82

github-actions · 2025-10-27T08:19:19Z

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 61067
GitHub commit: f4a36c7

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.

This was discussed in WordPress/wordpress-develop#9410 and decided to defer until after beta1. Fleshing out the phpdocs for the extender functions in https://core.trac.wordpress.org/browser/trunk/src/wp-includes/abilities-api.php should make it easier for people working with the abilities API Developed in WordPress/wordpress-develop#10412. Follw-up [61032]. Props jorbin, gziolo, mukesh27, jason_the_adams, westonruter. Fixes #64134. Built from https://develop.svn.wordpress.org/trunk@61067 git-svn-id: http://core.svn.wordpress.org/trunk@60403 1a063a9b-81f0-0310-95a4-ce76da25c4cd

This was discussed in WordPress/wordpress-develop#9410 and decided to defer until after beta1. Fleshing out the phpdocs for the extender functions in https://core.trac.wordpress.org/browser/trunk/src/wp-includes/abilities-api.php should make it easier for people working with the abilities API Developed in WordPress/wordpress-develop#10412. Follw-up [61032]. Props jorbin, gziolo, mukesh27, jason_the_adams, westonruter. Fixes #64134. Built from https://develop.svn.wordpress.org/trunk@61067 git-svn-id: https://core.svn.wordpress.org/trunk@60403 1a063a9b-81f0-0310-95a4-ce76da25c4cd

gziolo self-assigned this Oct 24, 2025

gziolo requested a review from Copilot October 24, 2025 11:34

Copilot AI reviewed Oct 24, 2025

View reviewed changes

src/wp-includes/abilities-api.php Show resolved Hide resolved

src/wp-includes/abilities-api.php Show resolved Hide resolved

src/wp-includes/abilities-api.php Show resolved Hide resolved

mukeshpanchal27 reviewed Oct 24, 2025

View reviewed changes

JasonTheAdams suggested changes Oct 24, 2025

View reviewed changes

src/wp-includes/abilities-api.php Show resolved Hide resolved

src/wp-includes/abilities-api.php Outdated Show resolved Hide resolved

src/wp-includes/abilities-api.php Outdated Show resolved Hide resolved

westonruter reviewed Oct 26, 2025

View reviewed changes

src/wp-includes/abilities-api.php Outdated Show resolved Hide resolved

src/wp-includes/abilities-api.php Outdated Show resolved Hide resolved

Abilities API: Improve inline documentation for public methods

0b6299f

gziolo force-pushed the update/document-abilities-api branch from 863cef1 to a8381b7 Compare October 27, 2025 08:03

Improve the documentation based on the review feedback

0392cd8

gziolo force-pushed the update/document-abilities-api branch from a8381b7 to 0392cd8 Compare October 27, 2025 08:04

github-actions bot closed this Oct 27, 2025

gziolo deleted the update/document-abilities-api branch October 27, 2025 08:20

	* @return WP_Ability\|null The unregistered ability instance on success, `null` on failure.
	* @return WP_Ability\|null The unregistered ability instance on success, null on failure.

	* @return bool\|null Whether to expect a closer for the currently-matched node,
	* or `null` if not matched on any token.
	*/
	public function expects_closer( ?WP_HTML_Token $node = null ): ?bool {

Abilities API: Improve inline documentation for public methods #10412

Abilities API: Improve inline documentation for public methods #10412

Uh oh!

Conversation

gziolo commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Oct 24, 2025

Test using WordPress Playground

Some things to be aware of

Uh oh!

mukeshpanchal27 Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

gziolo Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

mukeshpanchal27 Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

gziolo Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

JasonTheAdams left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Oct 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gziolo commented Oct 24, 2025 •

edited

Loading

github-actions bot commented Oct 24, 2025 •

edited

Loading