WordPress.org

Making WordPress.org

Opened 2 years ago

Closed 2 years ago

Last modified 2 years ago

#2339 closed defect (invalid)

Don't show the function signature for filters with missing DocBlocks.

Reported by: keesiemeijer Owned by:
Milestone: Priority: normal
Component: Developer Hub Keywords:
Cc:

Description

A function is undocumented if the DocBlock is missing or not found by the parser. This results in displaying no parameters in the signature for functions that have parameters. We should show a message that the function is undocumented instead of showing the signature.

Some examples of undocumented functions
https://developer.wordpress.org/reference/classes/_wp_editors/get_translation/
https://developer.wordpress.org/reference/hooks/image_size_names_choose-4/
https://developer.wordpress.org/reference/hooks/session_token_manager-2/

Change History (5)

#1 @keesiemeijer
2 years ago

  • Summary changed from Don't show the function signature for functions with missing DocBlocks. to Don't show the function signature for filters with missing DocBlocks.

#2 @keesiemeijer
2 years ago

It seems this only affects filters.

#3 @coffee2code
2 years ago

  • Resolution set to invalid
  • Status changed from new to closed

Thanks for pointing out these hooks! In their cases, they were vestiges of previous parsings before the parser ignored duplicate hooks. The primary instance of each hook includes their full documentation. As you noted, duplicate instances of hooks lack documentation, which is why we now ignore them during parsing.

I've trashed the duplicate hooks you mentioned, but there are more we haven't cleaned up yet (see #1085).

For your first link (for _WP_Editors::get_translation()) the lack of a docblock doesn't appear to impact the function signature or arguments display. (Though its DevHub page should indicate it is a private function... I'll investigate.)

Feel free to reopen if you still see an issue here.

#4 @keesiemeijer
2 years ago

You're right. So if I understand it correctly old parsings imported hooks without a DockBlock and they are still in the database. That would explain the wp_save_post_revision_check_for_changes filter which is not a duplicate hook but doesn't get imported when I parse it locally. It seems it isn't imported for developer.wordpress.org as well. When I remove the filter from the conditional it does get imported.

I will open a new ticket for wp_save_post_revision_check_for_changes.

#5 @keesiemeijer
2 years ago

The DocBlock for wp_save_post_revision_check_for_changes doesn't get imported because of a bug in the parser.

I've opened an issue for it in the GitHub repo.

Note: See TracTickets for help on using tickets.