![(please configure the [header_logo] section in trac.ini)](/chrome/site/your_project_logo.png){kind=logo}
Opened 12 months ago
Closed 12 months ago
#63746 closed enhancement (invalid)
Suggestion for Standardizing PHPDoc Comments for do_action Parameters in WordPress Core
| Reported by: | viralsampat | Owned by: | |
|---|---|---|---|
| Priority: | normal | Milestone: | |
| Component: | General | Version: | |
| Severity: | normal | Keywords: | has-patch dev-feedback needs-testing 2nd-opinion |
| Cc: | Focuses: | docs |
Description
Hello Team,
While reviewing the WordPress core files, I noticed that some do_action calls include PHPDoc blocks documenting their parameters. I believe standardizing PHPDoc comments for all do_action parameters across the core codebase could significantly improve code readability, enhance static analysis, and provide clearer documentation for developers.
This consistency would be particularly helpful for contributors and developers working with hooks, as it improves understanding of the data passed through actions.
It might be worth considering a standardized approach to this across the Core codebase.
Thank you,
Attachments (1)
Change History (3)
#1
@
12 months ago
My understanding is that this is standardized, it's just that the "standard" is intentionally to document them once in the "primary" location and then to reference where that primary documentation is if we need to reapply the hook somewhere else.
I'm assuming the reason is to maintain a single source of truth.
The proposed change here also shouldn't currently have any affect on static analysis, as our codebase doesn't use generics and most likely won't until well after PHPStan is merged, and it's advanced features adopted
#2
@
12 months ago
- Milestone Awaiting Review
- Resolution → invalid
- Status new → closed
Thanks for the ticket @viralsampat but this is already standardised. The two existing actions you've patched are fine. See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/ .
I have checked above mentioned issue and resolved it. Here, I have added my patch.