Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

PHPCS: Add XML based sniff documentation #146

Merged
merged 11 commits into from
Jul 31, 2019
Merged

PHPCS: Add XML based sniff documentation #146

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
8cd6cc0
Travis: verify XML sniff documentation is well-formed
jrfnl May 30, 2019
d87dd9b
IfElseDeclaration: add sniff documentation
jrfnl May 30, 2019
9dc7e8f
FileComment: add sniff documentation
jrfnl May 30, 2019
fe7e8fd
CodeCoverageIgnoreDeprecated: add sniff documentation
jrfnl May 30, 2019
3017348
NamespaceDeclaration: add sniff documentation
jrfnl May 30, 2019
841671d
FunctionSpacing: add sniff documentation
jrfnl May 30, 2019
86765fd
AlternativeFunctions: add sniff documentation
jrfnl May 30, 2019
9f896ff
TestDoubles: add sniff documentation
jrfnl May 30, 2019
839c5a4
FileName: add sniff documentation
jrfnl May 31, 2019
bdacd19
TestsHaveCoversTag: add sniff documentation
jrfnl May 31, 2019
5722968
CoversTag: add sniff documentation
jrfnl Jul 25, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions .travis.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ script:
# Validate the xml files.
# @link http://xmlsoft.org/xmllint.html
- if [[ "$SNIFF" == "1" ]]; then xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./Yoast/ruleset.xml; fi
- if [[ "$SNIFF" == "1" ]]; then xmllint --noout ./Yoast/Docs/*/*Standard.xml; fi
# Check the code-style consistency of the xml files.
- if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./Yoast/ruleset.xml <(xmllint --format "./Yoast/ruleset.xml"); fi
# Validate the composer.json file.
Expand Down
27 changes: 27 additions & 0 deletions Yoast/Docs/Commenting/CodeCoverageIgnoreDeprecatedStandard.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<?xml version="1.0"?>
<documentation title="Code Coverage Ignore Deprecated">
<standard>
<![CDATA[
Deprecated functions and methods should be ignored for code coverage calculations.
]]>
</standard>
<code_comparison>
<code title="Valid: Function marked as deprecated has a @codeCoverageIgnore tag.">
<![CDATA[
/**
* <em>@deprecated x.x
* @codeCoverageIgnore</em>
*/
function deprecated_function() {}
]]>
</code>
<code title="Invalid: Function marked as deprecated is missing a @codeCoverageIgnore tag.">
<![CDATA[
/**
* <em>@deprecated x.x</em>
*/
function deprecated_function() {}
]]>
</code>
</code_comparison>
</documentation>
110 changes: 110 additions & 0 deletions Yoast/Docs/Commenting/CoversTagStandard.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
<?xml version="1.0"?>
<documentation title="PHPUnit Covers Tag">
<standard>
<![CDATA[
The @covers tag used to annotate which code is coverage by a test should follow the specifications of PHPUnit with regards to the supported annotations.
See:
* https://phpunit.readthedocs.io/en/7.5/code-coverage-analysis.html#specifying-covered-code-parts
* https://phpunit.readthedocs.io/en/7.5/annotations.html#covers
]]>
</standard>
<code_comparison>
<code title="Valid: Correct covers tag annotation.">
<![CDATA[
class Some_Test extends TestCase {
/**
* Testing...
*
* @covers <em>Class_Name::method_name</em>
*/
function test_something() {}
}
]]>
</code>
<code title="Invalid: Incorrect covers tag annotation.">
<![CDATA[
class Some_Test extends TestCase {
/**
* Testing...
*
* @covers Class_Name::method_name<em>()</em>
*/
function test_something() {}
}
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
There should be no duplicate @covers tags for the same test.
]]>
</standard>
<code_comparison>
<code title="Valid: Unique @covers tags.">
<![CDATA[
class Some_Test extends TestCase {
/**
* Testing...
*
* @covers Name\Space\function_name
* @covers Class_Name
*/
function test_something() {}
}
]]>
</code>
<code title="Invalid: Duplicate @covers tag.">
<![CDATA[
class Some_Test extends TestCase {
/**
* Testing...
*
* @covers Name\Space\function_name
* @covers Class_Name
* @covers <em>Name\Space\function_name</em>
*/
function test_something() {}
}
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
There should be not be both a @covers tag as well as a @coversNothing tag for the same test.
]]>
</standard>
<code_comparison>
<code title="Valid: Either one or more @covers tags or a @coversNothing tag.">
<![CDATA[
class Some_Test extends TestCase {
/**
* Testing...
*
* <em>@covers ::globalFunction</em>
*/
function test_something() {}

/**
* Testing...
*
* <em>@coversNothing</em>
*/
function test_something_else() {}
}
]]>
</code>
<code title="Invalid: Both a @covers tag as well as a @coversNothing tag.">
<![CDATA[
class Some_Test extends TestCase {
/**
* Testing...
*
* <em>@coversNothing
* @covers ::globalFunction</em>
*/
function test_something() {}
}
]]>
</code>
</code_comparison>
</documentation>
204 changes: 204 additions & 0 deletions Yoast/Docs/Commenting/FileCommentStandard.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,204 @@
<?xml version="1.0"?>
<documentation title="File Comment">
<standard>
<![CDATA[
A file containing a (named) namespace declaration does not need a file docblock.
]]>
</standard>
<code_comparison>
<code title="Valid: Start of a namespaced file without a file docblock.">
<![CDATA[
<?php

<em>namespace Yoast\A\B;</em>

/**
* Class docblock.
*/
class {
...
]]>
</code>
<code title="Invalid: Start of a namespaced file with a file docblock.">
<![CDATA[
<?php
<em>/**
* File comment.
*/

namespace Yoast\A\B;</em>

/**
* Class docblock.
*/
class {
...
]]>
</code>
</code_comparison>

<standard>
<![CDATA[
A non-namespaced file must have a file docblock.
]]>
</standard>
<code_comparison>
<code title="Valid: Start of a non-namespaced file with a file docblock.">
<![CDATA[
<?php
<em>/**
* File comment.
*/</em>

/**
* Class docblock.
*/
class {
...
]]>
</code>
<code title="Invalid: Start of a non-namespaced file missing a file docblock.">
<![CDATA[
<?php
<em></em>
/**
* Class docblock.
*/
class {
...
]]>
</code>
</code_comparison>

<standard>
<![CDATA[
A file comment should be a docblock.
]]>
</standard>
<code_comparison>
<code title="Valid: File docblock.">
<![CDATA[
<?php
<em>/**
* File comment.
*/</em>
]]>
</code>
<code title="Invalid: File comment is not a docblock.">
<![CDATA[
<?php
<em>/*</em>
* File comment.
*/
]]>
</code>
</code_comparison>

<standard>
<![CDATA[
There must be no blank lines before the file comment.
]]>
</standard>
<code_comparison>
<code title="Valid: No blank line between the PHP open tag and the file comment.">
<![CDATA[
<?php<em>
</em>/**
* File comment.
*/
]]>
</code>
<code title="Invalid: Blank line(s) between the PHP open tag and the file comment.">
<![CDATA[
<?php<em>


</em>/**
* File comment.
*/
]]>
</code>
</code_comparison>

<standard>
<![CDATA[
There must be exactly one blank line after the file comment.
]]>
</standard>
<code_comparison>
<code title="Valid: One blank line after file comment.">
<![CDATA[
<?php
/**
* File comment.
*/<em>

</em>echo $something;
]]>
</code>
<code title="Invalid: No blank line or more than one blank line after file comment.">
<![CDATA[
<?php
/**
* File comment.
*/<em>
</em>echo $something;
]]>
</code>
</code_comparison>

<standard>
<![CDATA[
A file comment must contain a @package tag.
]]>
</standard>
<code_comparison>
<code title="Valid: File comment containing the @package tag.">
<![CDATA[
<?php
/**
* File comment.
*
* <em>@package Yoast\Package</em>
*/
]]>
</code>
<code title="Invalid: File comment missing the @package tag.">
<![CDATA[
<?php
/**
* File comment.
*/
]]>
</code>
</code_comparison>

<standard>
<![CDATA[
A file comment @package tag must have a package name.
]]>
</standard>
<code_comparison>
<code title="Valid: File comment @package tag with a package name.">
<![CDATA[
<?php
/**
* File comment.
*
* <em>@package Yoast\Package</em>
*/
]]>
</code>
<code title="Invalid: File comment @package tag without a package name.">
<![CDATA[
<?php
/**
* File comment.
*
* <em>@package</em>
*/
]]>
</code>
</code_comparison>

</documentation>