[wp-trac] [WordPress Trac] #56648: Improve comment type for Single line comment
WordPress Trac
noreply at wordpress.org
Wed Sep 28 15:46:05 UTC 2022
#56648: Improve comment type for Single line comment
------------------------------+-------------------------------
Reporter: rajanpanchal2028 | Owner: (none)
Type: enhancement | Status: closed
Priority: low | Milestone:
Component: General | Version:
Severity: minor | Resolution: invalid
Keywords: has-patch | Focuses: coding-standards
------------------------------+-------------------------------
Comment (by jrf):
Replying to [comment:3 davidbaumwald]:
> @jrf Thanks for the info! I also found the
[https://developer.wordpress.org/coding-standards/inline-documentation-
standards/php/#3-requires-and-includes inline docs standards], and it
seems to suggest a docblock, not a comment. I understand that you
suggested a short-form docblock, so that may be the same thing.
I only mentioned "short-form" docblocks here as that is the format used in
the comment which was reported.
Generally speaking, short-form docblocks are not all that commonly used in
WP, except for hook documentation when the actual documentation is
elsewhere, i.e. `/** Hook documented in ... */`.
> Is this something we could add/clarify in the docs for specifically
documenting includes?
>
> Also wondering if we should standardize this across the codebase.
>
> For some data, Core is currently a bit inconsistent: (Props to @desrosj
for the data here)
> * `require*` with full DocBlock: '''55 (26 within default themes)'''
> * `require*` with inline `/** comment */`: '''216'''
> * No include statements with preceding comment of either style.
Overhauling and improving the docs standards is on a long-term to-do list
of mine.
At this point in time, WP Core does **not** use the `WordPress-Docs`
standard for PHPCS, so any standardization would involve a lot of manual
work, both to fix existing things, as well as to safeguard that new
comments/docs comply.
The `Docs` standard ''should'' probably be used, but I'm the first to
point out that's it's not that great as it is at this moment and may yield
more annoyance and problems than that it solves.
So, for now, I'd leave this until we have a more solid set of base sniffs
for documentation in place and the `WordPress-Docs` standard could
actually properly enforce the standards.
--
Ticket URL: <https://core.trac.wordpress.org/ticket/56648#comment:4>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform
More information about the wp-trac
mailing list