Improve comment type for Single line comment

[rajanpanchal2028]

I have improved the comment for a single line on the admin-ajax.php file so it should be not / /.

[davidbaumwald]

There are actually quite a few single-line comments using this style in Core. Actually, there are more even just in admin-ajax.php.

I think it's probably best to address these in bulk(but perhaps one file at a time). We could also add these to the .git-blame-ignore-revs file.

I am cleaning the ticket details up a bit. I'm also unsetting the version for now. This goes back a long time, and I'm not able to quickly fine the exact changeset this traces back to. However, I know it's not the 6.0.2 version.

Finally, @rajanpanchal2028, your patch includes some unrelated changes that I don't think you intended to include.

[jrf]

Actually... (include|require)[_once] statements are considered structural elements for which a (short-form) docblock is the correct annotation format.

Also see: ​https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#3-definitions

[davidbaumwald]

@jrf Thanks for the info! I also found the ​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. Does Core follow PSR-5 in this instance or WPCS?

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.

[jrf]

Replying to davidbaumwald:

@jrf Thanks for the info! I also found the ​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.