Rendering error of the wp_register_ability_category() doc page

[satollo]

The page ​https://developer.wordpress.org/reference/functions/wp_register_ability_category/ has the Parameters section not rendered correctly; it's probably something related to the function's PHPDoc.

[satollo]

Screenshot of the rendering error

[iamadisingh]

The rendering issue on the page is being triggered by the <string, mixed> part of the @param tag.

Because of how the DevHub theme parses "hash notation" (the { brackets), the extra characters in the type declaration are confusing the formatter. It’s essentially a false positive where the theme sees the bracket but loses track of the variable name, resulting in the broken "mixed>" text we see on the site.

Here: ​https://github.com/WordPress/wporg-developer/blob/trunk/source/wp-content/themes/wporg-developer-2023/inc/formatting.php#L625

Same issue exists in wp_register_ability page: ​https://developer.wordpress.org/reference/functions/wp_register_ability/#parameters

This PR fixes rendering issues in the "Parameters" section for wp_register_ability() and wp_register_ability_category() on the Developer Hub. The issue is caused by a collision between modern PHP generic syntax (array<string, mixed>) and the legacy "hash notation" parser used by the DevHub theme. When these are combined, the parser fails to correctly identify the variable name, leading to malformed text being displayed on the site.

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

[hbhalodia]

Hi @iamadisingh @satollo,

This issue is not limited to just these two functions. We have many hooks (both actions and filters) and functions that follow a similar format for defining parameters and return types. For example: ​https://developer.wordpress.org/reference/hooks/post_states_html/

We should address this at a global level rather than fixing it by updating or removing the @param comments in individual cases, as seen in this PR: ​https://github.com/WordPress/wordpress-develop/pull/11574/changes

I also suggest updating the issue title and description to reflect a global issue that applies to all such functions. Since we are adopting PHPStan, it will require precise array notations for parameter and return types. Therefore, simply removing these annotations will not be a viable solution.

Thanks,

[iamadisingh]

Fair point, @hbhalodia. I agree that as we move toward stricter typing with PHPStan, the DevHub parser needs to be able to handle generic array notation without breaking.

It seems the issue is likely a collision with the legacy 'hash notation' parser in the DevHub theme. Since this would require a fix in the wporg-developer repo rather than core, I'll hold off on this PR for now. From what I can see, the conflict is possibly originating from the formatting logic here: ​https://github.com/WordPress/wporg-developer/blob/trunk/source/wp-content/themes/wporg-developer-2023/inc/formatting.php#L625 (or wherever that specific regex is handled).

[hbhalodia]

Also, I guess this should be reported here - ​https://meta.trac.wordpress.org/query?status=!closed&component=Developer+Hub, or at here ​https://github.com/WordPress/wporg-developer/issues instead of core trac.

It seems the issue is likely a collision with the legacy 'hash notation' parser in the DevHub theme. Since this would require a fix in the wporg-developer repo rather than core, I'll hold off on this PR for now. From what I can see, the conflict is possibly originating from the formatting logic here: ​https://github.com/WordPress/wporg-developer/blob/trunk/source/wp-content/themes/wporg-developer-2023/inc/formatting.php#L625 (or wherever that specific regex is handled).

Yes that's correct. You can create/report the issue upstream and add the core trac link there for reference and discussion.

[hbhalodia]

We have an active ticket here - ​https://github.com/WordPress/phpdoc-parser/issues/246, probably the same thing and active PR ​https://github.com/WordPress/phpdoc-parser/pull/247.

I would just bump to the issue and PR to reflect this ticket so that it get's some priority.

Thanks,