Skip to content

Docs: Add missing @since tags to eleven functions and methods - #13588

Open
som3669 wants to merge 1 commit into
WordPress:trunkfrom
som3669:65860-add-missing-since-tags
Open

som3669 wants to merge 1 commit into
WordPress:trunkfrom
som3669:65860-add-missing-since-tags

Conversation

@som3669

@som3669 som3669 commented Sep 17, 2026

Copy link
Copy Markdown

The Inline Documentation Standards require an @since tag on every function and method. These eleven have complete @param/@return documentation but no @since at all, so their handbook reference pages show no version at all.

Three of them are public HTML API methods — WP_HTML_Tag_Processor::release_bookmark() has been undocumented since it shipped in 6.2.0.

Function / method @since
WP_REST_Block_Directory_Controller::register_routes() 5.5.0
WP_Sitemaps_Stylesheet::render_stylesheet() 5.5.0
WP_HTML_Tag_Processor::release_bookmark() 6.2.0
WP_REST_Font_Families_Controller::prepare_font_face_links() 6.5.0
WP_Token_Map::to_array() 6.6.0
WP_HTML_Tag_Processor::get_doctype_info() 6.7.0
WP_HTML_Processor::get_namespace() 6.7.0
WP_Block_Processor::is_block_type() 6.9.0
WP_REST_Comments_Controller::check_post_type_supports_notes() 6.9.0
WP_Theme_JSON::process_pseudo_selectors() 7.0.0
wp_register_custom_css_support() 7.0.0

How the versions were determined

For each function, the commit that first introduced it was found with git log -S on its file, and the earliest release tag containing that commit was taken as the version. Each result was then cross-checked against the previous release branch (git show <prior tag>:<file>) to confirm the function was not already present there — for example release_bookmark() is absent from 6.1.12, and get_doctype_info() is absent from the 6.6.7 copy of a file that otherwise already existed.

Each version also lines up with the release that introduced the surrounding feature: sitemaps and the block directory in 5.5, the HTML API in 6.2, the Font Library in 6.5, WP_Token_Map in 6.6, and WP_Block_Processor in 6.9.

Testing

  • php -l clean on all ten changed files.
  • git diff --check clean.
  • Documentation only, no behaviour change — no runtime code is touched.

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

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Repository scanning to identify missing documentation tags, and drafting this change. Reviewed by me.

The inline documentation standards require an `@since` tag on every function
and method. These eleven have complete `@param`/`@return` documentation but no
`@since` at all, so the handbook reference pages for them show no version.

Three are public HTML API methods: `WP_HTML_Tag_Processor::release_bookmark()`
has been undocumented since it shipped in 6.2.0.

Each version was determined from the commit that introduced the function,
cross-checked against the previous release branch to confirm the function was
not present there:

* `WP_REST_Block_Directory_Controller::register_routes()`      5.5.0
* `WP_Sitemaps_Stylesheet::render_stylesheet()`                5.5.0
* `WP_HTML_Tag_Processor::release_bookmark()`                  6.2.0
* `WP_REST_Font_Families_Controller::prepare_font_face_links()` 6.5.0
* `WP_Token_Map::to_array()`                                   6.6.0
* `WP_HTML_Tag_Processor::get_doctype_info()`                  6.7.0
* `WP_HTML_Processor::get_namespace()`                         6.7.0
* `WP_Block_Processor::is_block_type()`                        6.9.0
* `WP_REST_Comments_Controller::check_post_type_supports_notes()` 6.9.0
* `WP_Theme_JSON::process_pseudo_selectors()`                  7.0.0
* `wp_register_custom_css_support()`                           7.0.0

See #65860.
@github-actions

Copy link
Copy Markdown

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 som9663.

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

@github-actions

Copy link
Copy Markdown

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

  • 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.

/**
* Registers the style block attribute for block types that support it.
*
* @since 7.0.0

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks — backported in WordPress/gutenberg#83116

While checking the rest of this PR against Gutenberg lib/, WP_Theme_JSON::process_pseudo_selectors() turned out to be synced too (lib/class-wp-theme-json-gutenberg.php), so I included it in the same Gutenberg PR. The other nine functions here have no counterpart in lib/, so they should be core-only.

One thing worth a second opinion: lib/block-supports/custom-css.php has no @since tags at all today, so the Gutenberg side adds the first one to that file. lib/class-wp-theme-json-gutenberg.php already uses @since throughout, so that half is consistent either way. Happy to drop the custom-css.php change from both PRs if you would rather leave that file alone.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants