Test documentation standards

[ScreamingDev]

Please add tests for documentation standards:
https://make.wordpress.org/core/handbook/inline-documentation-standards/php-documentation-standards/

[GaryJones]

Not sure if we'd test with tokens or with Reflection. If the latter, WP-Parser may have code we could use, cc @Rarst.

[Rarst]

This is not the parser you are looking for. waves hand

[JDGrimes]

PHPDocumentor uses reflection, so if you are going to leverage its code, I think you'll have to use reflection. I'm doubtful you'd find anything helpful out of WP-Parser at the moment though.

[JDGrimes]

On second thought, it would be great to leverage WP-Parser's exporter, but I think it's still entangled a bit with WP-CLI, so it might take a bit of work. It would parse hook docs for you though, which is something PHPDocumentor isn't gonna do on its own.

[GaryJones]

Anyone happen to know if individual tokens might actually exist inside a comment block? I'm guessing not...

[JDGrimes]

Anyone happen to know if individual tokens might actually exist inside a comment block? I'm guessing not...

No, they don't.

[JDGrimes]

If you want to take a whack at leveraging WP-Parser, take a look at the parse_files() function. You could use that to parse the file's docs into an array, which you could check for the expected info. (The function parses some other information as well, like what functions are used, but you can just ignore that part of the returned data.)

[ScreamingDev]

Please approve this gist (test for @since): https://gist.github.com/sourcerer-mike/38f9984d559a5a147023

It is copied from PEAR Coding Standard and if you agree I help develop in that way. Please note that the comments in those files are not revised and it only tests for @since.

@GaryJones

Anyone happen to know if individual tokens might actually exist inside a comment block? I'm guessing not...

If you mean something like "T_DOC_COMMENT_OPEN_TAG" then the answer is yes: https://pear.php.net/package/PHP_CodeSniffer/docs/latest/PHP_CodeSniffer/_PHP_CodeSniffer-2.0.0RC1---CodeSniffer---Tokens.php.html

[GaryJones]

Please note that the comments in those files are not revised and it only tests for @SInCE

If it could test for all it mentions (except the A return type exists, since WP does follow that), then it would be a great start.

Getting ahead of ourselves, I'd foresee this as being a WordPress-Docs ruleset, since I could imagine that folks would want to test documentation standards separately from non-comment code quality.

Updated: Actually, I disagree with that. Documentation is a vital part of coding, it's a standard on make.wp.org, so we should be encouraging it as part of the WordPress-Core / Extra standards like non-comment standards.

[GaryJones]

https://github.com/squizlabs/PHP_CodeSniffer/blob/phpcs-fixer/CodeSniffer/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php

It's not quite perfect for WP, but it's an extremely good starting point.

[GaryJones]

See https://github.com/squizlabs/PHP_CodeSniffer/tree/phpcs-fixer/CodeSniffer/Standards/Squiz/Sniffs/Commenting
and
https://github.com/squizlabs/PHP_CodeSniffer/tree/phpcs-fixer/CodeSniffer/Standards/Generic/Sniffs/Commenting

Some will need WP variants as the Squiz and Generic ones don't quite match what we want, or we need to use the originals but with severity = 0 so it's not reported.

[westonruter]

See @Rarst's tweet in regards to incorporating the Squiz.Commenting sniffs: https://twitter.com/rarst/status/567237335495221248