Skip to content

Commit

Permalink
Streamline WPCS in file documentation. (#651)
Browse files Browse the repository at this point in the history 
* Update the file and class @Package tag and remove the @category tag.

Follow the standard as described in https://www.phpdoc.org/docs/latest/references/phpdoc/tags/package.html

The @category tag is considered deprecated. A hierarchical @Package tag should be used instead.

Ref: https://www.phpdoc.org/docs/latest/references/phpdoc/tags/category.html

* Use correct version number for the newly deprecated classes.

* Fix some - unintentional - parse errors in the test files.

* Attempt to lead by example comment-wise in the unit tests.

Capitalization, punctuation and some spelling.

* Proper capitalization and punctuation for class end comments.

* Remove `//end` comments for methods and conditionals < 35 lines.

* Simplify the test file method doc blocks.

* Various documentation fixes, largely based on PHPCS Docs output.

* Make sure any function which will be passed the $phpcsFile has the right type hint.

But only if it doesn't conflict with upstream function signatures.

* Verify and update the docblocks for all files and classes.

Based on Git file history:

* Add @SInCE tags to all classes.
* Add @SInCE tags to properties and methods if they weren't included from the start.
* Verify/Fix a number of @author tags.
* Remove old/copied over/incorrect PHPCS tags.
* Where necessary improved/corrected the class description.

Also:
* Consistent tag order in class doc blocks.
* Fix tag alignment.
* Remove redundant explanation in unit test class doc blocks.
* Sync the description line of the unit test class doc blocks.

* Add handbook links to a number of sniffs.

* Add reference to upstream sniff a sniff is based upon.

Includes information on when the sniff was last synced with the upstream sniff if applicable and available.

* Add @license tag and @link tag to the WPCS GH repo, to all file level doc blocks.

License tag as per https://www.phpdoc.org/docs/latest/references/phpdoc/tags/license.html

* Add the docs ruleset to the coding standard for WPCS itself.

* Add @SInCE class changelogs for PR #647.

* Fix minor grammar error.

* Updated `@since` tags for `2014-12-11` release to `0.3.0`.

* Re-instate previously removed @SInCE tags.

* Updated based on feedback.

* Adjusted the @Package tags as per discussion in the PR thread
* Removed the @link tag to the handbook at the file level doc block
* Removed the @author tags
  • Loading branch information
@jrfnl @JDGrimes
jrfnl authored and JDGrimes committed Oct 7, 2016
1 parent 46bf0a2 commit 616290a
Show file tree
Hide file tree
Showing 133 changed files with 1,950 additions and 2,237 deletions.
52 changes: 33 additions & 19 deletions Sniffs/WP/I18nSniff.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,20 @@
/**
* WordPress Coding Standard.
*
* @category PHP
* @package PHP_CodeSniffer
* @link https://make.wordpress.org/core/handbook/best-practices/coding-standards/
* @package WPCS\WordPressCodingStandards
* @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
* @license https://opensource.org/licenses/MIT MIT
*/

/**
* WordPress_Sniffs_WP_I18nSniff
* Makes sure WP internationalization functions are used properly.
*
* Makes sure internationalization functions are used properly.
* @link https://make.wordpress.org/core/handbook/best-practices/internationalization/
* @link https://developer.wordpress.org/plugins/internationalization/
*
* @category PHP
* @package PHP_CodeSniffer
* @author Shady Sharaf <[email protected]>
* @package WPCS\WordPressCodingStandards
*
* @since 0.10.0
*/
class WordPress_Sniffs_WP_I18nSniff extends WordPress_Sniff {

Expand All @@ -37,6 +38,11 @@ class WordPress_Sniffs_WP_I18nSniff extends WordPress_Sniff {
*/
static $text_domain_override;

/**
* The I18N functions in use in WP.
*
* @var array <string function name> => <string function type>
*/
public $i18n_functions = array(
'translate' => 'simple',
'__' => 'simple',
Expand All @@ -58,13 +64,17 @@ class WordPress_Sniffs_WP_I18nSniff extends WordPress_Sniff {

/**
* These Regexes copied from http://php.net/manual/en/function.sprintf.php#93552
*
* @var string
*/
static $sprintf_placeholder_regex = '/(?:%%|(%(?:[0-9]+\$)?[+-]?(?:[ 0]|\'.)?-?[0-9]*(?:\.[0-9]+)?[bcdeufFos]))/';
public static $sprintf_placeholder_regex = '/(?:%%|(%(?:[0-9]+\$)?[+-]?(?:[ 0]|\'.)?-?[0-9]*(?:\.[0-9]+)?[bcdeufFos]))/';

/**
* "Unordered" means there's no position specifier: '%s', not '%2$s'.
*
* @var string
*/
static $unordered_sprintf_placeholder_regex = '/(?:%%|(?:%[+-]?(?:[ 0]|\'.)?-?[0-9]*(?:\.[0-9]+)?[bcdeufFosxX]))/';
public static $unordered_sprintf_placeholder_regex = '/(?:%%|(?:%[+-]?(?:[ 0]|\'.)?-?[0-9]*(?:\.[0-9]+)?[bcdeufFosxX]))/';

/**
* Returns an array of tokens this test wants to listen for.
Expand All @@ -82,7 +92,7 @@ public function register() {
*
* @param PHP_CodeSniffer_File $phpcs_file The file being scanned.
* @param int $stack_ptr The position of the current token
* in the stack passed in $tokens.
* in the stack passed in $tokens.
*
* @return void
*/
Expand Down Expand Up @@ -211,7 +221,7 @@ public function process( PHP_CodeSniffer_File $phpcs_file, $stack_ptr ) {
* Check if supplied tokens represent a translation text string literal.
*
* @param PHP_CodeSniffer_File $phpcs_file The file being scanned.
* @param array $context
* @param array $context Context (@todo needs better description).
* @return bool
*/
protected function check_argument_tokens( PHP_CodeSniffer_File $phpcs_file, $context ) {
Expand Down Expand Up @@ -274,8 +284,10 @@ protected function check_argument_tokens( PHP_CodeSniffer_File $phpcs_file, $con
* Check for inconsistencies between single and plural arguments.
*
* @param PHP_CodeSniffer_File $phpcs_file The file being scanned.
* @param array $single_context
* @param array $plural_context
* @param int $stack_ptr The position of the current token
* in the stack passed in $tokens.
* @param array $single_context Single context (@todo needs better description).
* @param array $plural_context Plural context (@todo needs better description).
* @return void
*/
protected function compare_single_and_plural_arguments( PHP_CodeSniffer_File $phpcs_file, $stack_ptr, $single_context, $plural_context ) {
Expand All @@ -289,7 +301,7 @@ protected function compare_single_and_plural_arguments( PHP_CodeSniffer_File $ph
$plural_placeholders = $plural_placeholders[0];

// English conflates "singular" with "only one", described in the codex:
// https://codex.wordpress.org/I18n_for_WordPress_Developers#Plurals
// https://codex.wordpress.org/I18n_for_WordPress_Developers#Plurals .
if ( count( $single_placeholders ) < count( $plural_placeholders ) ) {
$error_string = 'Missing singular placeholder, needed for some languages. See https://codex.wordpress.org/I18n_for_WordPress_Developers#Plurals';
$single_index = $single_context['tokens'][0]['token_index'];
Expand All @@ -310,7 +322,7 @@ protected function compare_single_and_plural_arguments( PHP_CodeSniffer_File $ph
* Check the string itself for problems.
*
* @param PHP_CodeSniffer_File $phpcs_file The file being scanned.
* @param array $context
* @param array $context Context (@todo needs better description).
* @return void
*/
protected function check_text( PHP_CodeSniffer_File $phpcs_file, $context ) {
Expand Down Expand Up @@ -348,9 +360,11 @@ protected function check_text( PHP_CodeSniffer_File $phpcs_file, $context ) {
}
}

// NoEmptyStrings.

// Strip placeholders and surrounding quotes.
/*
* NoEmptyStrings.
*
* Strip placeholders and surrounding quotes.
*/
$non_placeholder_content = trim( $content, "'" );
$non_placeholder_content = preg_replace( self::$sprintf_placeholder_regex, '', $non_placeholder_content );

Expand Down
50 changes: 25 additions & 25 deletions Tests/WP/I18nUnitTest.inc
View file
Original file line number Diff line number Diff line change
@@ -1,46 +1,46 @@
<?php

__( "hell$varo", 'my-slug' ); // Bad, shouldn't use a string with variables
__( "hell$varo", 'my-slug' ); // Bad, shouldn't use a string with variables.

__( "hell\$varo", 'my-slug' ); // OK, Variable is not interpolated.
__( "hell\\$varo", 'my-slug' ); // Bad, is interpolated.
__( "hell\\\$varo", 'my-slug' ); // OK, variable is escaped.

__( $var, 'my-slug' ); // Bad, shouldn't use variables
__( $var, 'my-slug' ); // Bad, shouldn't use variables.

__( 'string', SOMETHING ); // Bad, shouldn't use CONSTANTS
__( 'string', SOMETHING ); // Bad, shouldn't use CONSTANTS.

__( 'string' . $var, 'my-slug' ); // Bad, shouldn't use variable for string
__( 'string' . $var, 'my-slug' ); // Bad, shouldn't use variable for string.

__( $var . 'string', 'my-slug' ); // Bad, shouldn't use variable for string
__( $var . 'string', 'my-slug' ); // Bad, shouldn't use variable for string.

__( SOMETHING, 'my-slug' ); // Bad, shouldn't use constant for string
__( SOMETHING, 'my-slug' ); // Bad, shouldn't use constant for string.

__( 'string' . SOMETHING, 'my-slug' ); // Bad, shouldn't use constant for string
__( 'string' . SOMETHING, 'my-slug' ); // Bad, shouldn't use constant for string.

__( SOMETHING . 'string', 'my-slug' ); // Bad, shouldn't use variable for string
__( SOMETHING . 'string', 'my-slug' ); // Bad, shouldn't use variable for string.

__( 'string', $domain ); // Bad, shouldn't use variable for domain
__( 'string', $domain ); // Bad, shouldn't use variable for domain.

__( 'string', 'my' . $domain ); // Bad, shouldn't use variable for domain
__( 'string', 'my' . $domain ); // Bad, shouldn't use variable for domain.

__( 'string', $domain . 'my-slug' ); // Bad, shouldn't use variable for domain
__( 'string', $domain . 'my-slug' ); // Bad, shouldn't use variable for domain.

__( 'string', 'my-slug' ); // Good
__( 'string', 'my-slug' ); // Good.

_x( 'string', 'context', 'my-slug' ); // Good
_x( 'string', 'context', 'my-slug' ); // Good.

_x( 'string', $var, 'my-slug' ); // Bad, shouldn't use variable for context
_x( 'string', $var, 'my-slug' ); // Bad, shouldn't use variable for context.

_x( 'string', 'context' . $var, 'my-slug' ); // Bad, shouldn't use variable for context
_x( 'string', 'context' . $var, 'my-slug' ); // Bad, shouldn't use variable for context.

_x( 'string', $var . 'context', 'my-slug' ); // Bad, shouldn't use variable for context
_x( 'string', $var . 'context', 'my-slug' ); // Bad, shouldn't use variable for context.

_x( 'string', SOMETHING, 'my-slug' ); // Bad, shouldn't use constant for context
_x( 'string', SOMETHING, 'my-slug' ); // Bad, shouldn't use constant for context.

_x( 'string', SOMETHING . 'context', 'my-slug' ); // Bad, shouldn't use constant for context
_x( 'string', SOMETHING . 'context', 'my-slug' ); // Bad, shouldn't use constant for context.

_x( 'string', 'context' . SOMETHING, 'my-slug' ); // Bad, shouldn't use constant for context
_x( 'string', 'context' . SOMETHING, 'my-slug' ); // Bad, shouldn't use constant for context.

_n( 'I have %d cat.', 'I have %d cats.', $number ); // Bad, no text domain.
_n( 'I have %d cat.', 'I have %d cats.', $number, 'my-slug' ); // OK.
Expand Down Expand Up @@ -72,8 +72,8 @@ translate_with_gettext_context( 'foo', 'bar', 'my-slug' ); // Bad, low-level API
_( 'foo', 'my-slug' ); // Bad.

__( 'foo', 'my-slug', 'too-many-args' ); // Bad.
_x( 'string', 'context', 'my-slug', 'too-many-args' ); // Bad
_n( 'I have %d cat.', 'I have %d cats.', $number, 'my-slug', 'too-many-args' ); // Bad
_x( 'string', 'context', 'my-slug', 'too-many-args' ); // Bad.
_n( 'I have %d cat.', 'I have %d cats.', $number, 'my-slug', 'too-many-args' ); // Bad.
_n_noop( 'I have %d cat.', 'I have %d cats.', 'my-slug', 'too-many-args' ); // Bad.
_nx_noop( 'I have %d cat.', 'I have %d cats.', 'Not really.', 'my-slug', 'too-many-args' ); // Bad.

Expand Down Expand Up @@ -102,7 +102,7 @@ _n_noop( 'I have a cat.', 'I have %d cats.', 'my-slug' ); // Bad, singular shoul
_nx( 'I have a cat.', 'I have %d cats.', $number, 'Not really.', 'my-slug' ); // Bad, singular should have placeholder.
_nx_noop( 'I have a cat.', 'I have %d cats.', 'Not really.', 'my-slug' ); // Bad, singular should have placeholder.

__( '%s', 'my-slug' ); // Bad, don't waste translator's time
__( '%1$s%2$s', 'my-slug' ); // Bad, don't waste translator's time
_n( 'I have %d cat.', '%d', $number, 'my-slug' ); // Bad, move the logic out of the translation
__( '\'%s\'', 'my-slug' ); // OK (ish. this is a technical test, not a great string)
__( '%s', 'my-slug' ); // Bad, don't waste translator's time.
__( '%1$s%2$s', 'my-slug' ); // Bad, don't waste translator's time.
_n( 'I have %d cat.', '%d', $number, 'my-slug' ); // Bad, move the logic out of the translation.
__( '\'%s\'', 'my-slug' ); // OK (ish. this is a technical test, not a great string).
30 changes: 13 additions & 17 deletions Tests/WP/I18nUnitTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,22 @@
/**
* Unit test class for WordPress Coding Standard.
*
* @category PHP
* @package PHP_CodeSniffer
* @link https://make.wordpress.org/core/handbook/best-practices/coding-standards/
* @package WPCS\WordPressCodingStandards
* @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
* @license https://opensource.org/licenses/MIT MIT
*/

/**
* Unit test class for the I18nUnit sniff.
* Unit test class for the I18n sniff.
*
* @category PHP
* @package PHP_CodeSniffer
* @author Shady Sharaf <[email protected]>
* @package WPCS\WordPressCodingStandards
* @since 0.10.0
*/
class WordPress_Tests_WP_I18nUnitTest extends AbstractSniffUnitTest {

/**
* Fill in the $text_domain_override property to test domain check functionality.
*/
protected function setUp() {
// @todo Should be possible via self::$phpcs->setSniffProperty( 'WordPress_Sniffs_WP_I18nSniff', 'text_domain', 'my-slug' );
WordPress_Sniffs_WP_I18nSniff::$text_domain_override = 'my-slug';
Expand All @@ -25,10 +27,7 @@ protected function setUp() {
/**
* Returns the lines where errors should occur.
*
* The key of the array should represent the line number and the value
* should represent the number of errors that should occur on that line.
*
* @return array(int => int)
* @return array <int line number> => <int number of errors>
*/
public function getErrorList() {
return array(
Expand Down Expand Up @@ -87,10 +86,7 @@ public function getErrorList() {
/**
* Returns the lines where warnings should occur.
*
* The key of the array should represent the line number and the value
* should represent the number of warnings that should occur on that line.
*
* @return array(int => int)
* @return array <int line number> => <int number of warnings>
*/
public function getWarningList() {
return array(
Expand All @@ -101,6 +97,6 @@ public function getWarningList() {
102 => 1,
103 => 1,
);
} // end getWarningList()
}

} // end class.
} // End class.
20 changes: 12 additions & 8 deletions WordPress/AbstractArrayAssignmentRestrictionsSniff.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,21 @@
/**
* WordPress Coding Standard.
*
* @category PHP
* @package PHP_CodeSniffer
* @link https://make.wordpress.org/core/handbook/best-practices/coding-standards/
* @package WPCS\WordPressCodingStandards
* @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
* @license https://opensource.org/licenses/MIT MIT
*/

/**
* Restricts array assignment of certain keys.
*
* @category PHP
* @package PHP_CodeSniffer
* @author Shady Sharaf <[email protected]>
* @package WPCS\WordPressCodingStandards
*
* @since 0.3.0
* @since 0.10.0 Class became a proper abstract class. This was already the behaviour.
* Moved the file and renamed the class from
* `WordPress_Sniffs_Arrays_ArrayAssignmentRestrictionsSniff` to
* `WordPress_AbstractArrayAssignmentRestrictionsSniff`.
*/
abstract class WordPress_AbstractArrayAssignmentRestrictionsSniff extends WordPress_Sniff {

Expand Down Expand Up @@ -47,7 +51,7 @@ public function register() {
T_DOUBLE_QUOTED_STRING,
);

} // end register()
}

/**
* Groups of variables to restrict.
Expand Down Expand Up @@ -195,4 +199,4 @@ public function process( PHP_CodeSniffer_File $phpcsFile, $stackPtr ) {
*/
abstract public function callback( $key, $val, $line, $group );

} // end class
} // End class.
Loading

0 comments on commit 616290a

Please sign in to comment.