Improved docs

gmazzap · gmazzap · commit f5ef9ed9fe3f · 2018-01-29T18:40:32.000+01:00
diff --git a/Inpsyde/Sniffs/CodeQuality/ElementNameMinimalLengthSniff.php b/Inpsyde/Sniffs/CodeQuality/ElementNameMinimalLengthSniff.php
@@ -66,7 +66,7 @@ public function process(File $file, $position)
             $this->minLength
         );
 
-        $file->addError($message, $position, 'ElementNameMinimalLength');
+        $file->addError($message, $position, 'TooShort');
     }
 
     /**
diff --git a/Inpsyde/Sniffs/CodeQuality/ForbiddenPublicPropertySniff.php b/Inpsyde/Sniffs/CodeQuality/ForbiddenPublicPropertySniff.php
@@ -54,7 +54,7 @@ public function process(File $file, $position)
             $file->addError(
                 'Do not use public properties. Use method access instead.',
                 $position,
-                'ForbiddenPublicProperty'
+                'Found'
             );
         }
     }
diff --git a/Inpsyde/Sniffs/CodeQuality/FunctionLengthSniff.php b/Inpsyde/Sniffs/CodeQuality/FunctionLengthSniff.php
@@ -52,7 +52,7 @@ public function process(File $file, $position)
                 $this->maxLength
             );
 
-            $file->addError($error, $position, 'FunctionLength');
+            $file->addError($error, $position, 'TooLong');
         }
     }
 
diff --git a/Inpsyde/Sniffs/CodeQuality/MaxNestingLevelSniff.php b/Inpsyde/Sniffs/CodeQuality/MaxNestingLevelSniff.php
@@ -105,7 +105,7 @@ private function handleNestingLevel(int $nestingLevel)
                 $nestingLevel
             );
 
-            $this->file->addError($error, $this->position, 'MaxNestingLevel');
+            $this->file->addError($error, $this->position, 'TooNested');
         }
     }
 
diff --git a/Inpsyde/Sniffs/CodeQuality/PropertyPerClassLimitSniff.php b/Inpsyde/Sniffs/CodeQuality/PropertyPerClassLimitSniff.php
@@ -56,7 +56,7 @@ public function process(File $file, $position)
                 $this->maxCount
             );
 
-            $file->addWarning($message, $position, 'PropertyPerClassLimit');
+            $file->addWarning($message, $position, 'TooMuchProperties');
         }
     }
 }
diff --git a/Inpsyde/ruleset.xml b/Inpsyde/ruleset.xml
@@ -71,13 +71,6 @@
 	<!--
 	Generic and common sense sanity.
 	-->
-	<rule ref="Generic.ControlStructures.InlineControlStructure"/>
-	<rule ref="Generic.Files.ByteOrderMark"/>
-	<rule ref="Generic.Files.LineEndings">
-		<properties>
-			<property name="eolChar" value="\n"/>
-		</properties>
-	</rule>
 	<rule ref="Squiz.PHP.Eval"/>
 
 	<!--
diff --git a/README.md b/README.md
@@ -91,20 +91,45 @@ internationalization functions are called with the proper text domain.
 
 ## PSR-1 & PSR-2
 
-See http://www.php-fig.org/psr/psr-1/ and http://www.php-fig.org/psr/psr-2/
+See http://www.php-fig.org/psr/psr-1/ and http://www.php-fig.org/psr/psr-2/.
+
+The tree of used rules are listed in the `/docs/rules-list/psr.md` file in this repo.
 
 
 ## VariableAnalysis
 
 See https://github.com/sirbrillig/phpcs-variable-analysis
 
+The tree of used rules are listed in the `/docs/rules-list/variable-analysis.md` file in this repo.
+
 
 ## Neutron Standard
 
 See https://github.com/Automattic/phpcs-neutron-standard
 
-All Neutron Standard rules are included except "Function size" (handles in custom rules, see below)
-and "Variable Functions" rules.
+Almost all Neutron Standard rules are included.
+
+The tree of used rules are listed in the `/docs/rules-list/neutron-standard.md` file in this repo.
+
+
+## WordPress Coding Standard
+
+To ensure code quality, and compatibility with VIP, several WordPress Coding Standard rules have been
+"cherry picked" from WP coding standards.
+
+See https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.
+
+The tree of used rules are listed in the `/docs/rules-list/wordpress.md` file in this repo.
+
+
+## Generic Rules
+
+Some rules are also included from PHP cCode Sniffer itself. Those rules fall in the
+"Generic", "Squiz" and "PEAR" namespace.
+
+Those rules are included by other styles, mainly by PSR-1 and PSR-2.
+
+The tree of used rules are listed in the `/docs/rules-list/generic.md` file in this repo.
 
 
 ## Custom Rules
@@ -122,47 +147,121 @@ Customs rules are:
 - Max 10 properties per class
 - Max 50 lines per method
 
+The tree of used rules are listed in the `/docs/rules-list/custom.md` file in this repo.
 
-## WordPress Coding Standard
+-------------
 
-To ensure code quality, and compatibility with VIP, several WordPress Coding Standard rules have been
-"cherry picked" from WP coding standards.
-See https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.
+# Removing or Disabling Rules
+
+## Rules Tree
+
+Sometimes it is necessary to don't follow some rules.
+To avoid error reporting is is possible to:
+
+- Removing rules for an entire project via configuration
+- Disabling rules from code, only is specific places
+
+In both cases it is possible to remove or disable:
+
+- a whole standard
+- a standard subset
+- a single sniff
+- a single rules
 
-Included rules are:
-
-- `WordPress.VIP.SessionVariableUsage` - Avoid usages of `$_SESSION` super global
-- `VIP.SessionFunctionsUsage` - Avoid usages of session-related functions
-- `WordPress.VIP.SuperGlobalInputUsage` - Avoid usages of sulerglobals: `$_GET`, `$_POST`, etc
-- `WordPress.VIP.ValidatedSanitizedInput` - Avoid non-validated/sanitized input (`$_GET`, `$_POST`, etc)
-- `WordPress.Security.EscapeOutput` - Verifies that all outputted strings are escaped.
-- `WordPress.Security.NonceVerification` - Checks that nonce verification accompanies form processing.
-- `WordPress.WP.AlternativeFunctions.curl` - Discourages the use of cURL functions and suggests WP alternatives.
-- `WordPress.WP.DiscouragedConstants` - Warns against usage of discouraged WP constants
-- `WordPress.WP.I18n` - Makes sure WP internationalization functions are used properly. Also checks text domain if set in `phpcs.xml`
-- `WordPress.Arrays.CommaAfterArrayItem` - Ensure last item of arrays have a comma
-- `WordPress.PHP.StrictComparisons` - Enforces Strict Comparison checks
-- `WordPress.PHP.StrictInArray` - Prevent calling `in_array()`, `array_search()` and `array_keys()` without `true` as the 3rd parameter
-- `WordPress.PHP.POSIXFunctions` - Suggest usage of PCRE functions (`preg_*`) instead of POSIX alternative
-- `WordPress.PHP.RestrictedPHPFunctions` - Prevent usage of `create_function`
-- `WordPress.PHP.DiscouragedPHPFunctions` - Discourage usage of soem PHP functions (runtime configuration, system calls)
-- `WordPress.PHP.DevelopmentFunctions` - Prevent usage of development PHP functions (`error_log`, `var_dump`, `var_export`, `print_r`...)
-
-Any of these rules (just like the others) can be excluded in the `phpcs.xml`, using a syntax like this:
+The for things above are in hierarchical relationship: a _standard_ is made of one
+or more _subset_, each subset contains one or more _sniff_ and each sniff contains
+one or more rule.
+
+The folder `/docs/rules-list/` of this repo contains 6 files, each of them contain
+the rules _tree_ for one (or few related) standard(s).
+
+For example, in the file `docs/rules-list/psr.md` is is possible to read something
+like:
+
+```
+- PSR1
+    - PSR1.Classes
+        - PSR1.Classes.ClassDeclaration
+            - PSR1.Classes.ClassDeclaration.MultipleClasses
+```
+
+Where:
+- "_PSR1_" is the standard
+- "_PSR1.Classes_" is the subset
+- "_PSR1.Classes.ClassDeclaration_" is the sniff
+- "_PSR1.Classes.ClassDeclaration.MultipleClasses_" is the rule
+
+
+## Remove rules via configuration file
+
+Rules can be removed for the entire project by using a custom `phpcs.xml`, with
+ a syntax like this:
 
 ```xml
 <?xml version="1.0"?>
 <ruleset name="MyProjectCodingStandard">
 
 	<rule ref="Inpsyde">
-		<exclude name="WordPress.PHP.DevelopmentFunctions"/>
+		<exclude name="PSR1.Classes.ClassDeclaration"/>
 	</rule>
 
 </ruleset>
 ```
 
+In the example above, the _sniff_ `PSR1.Classes.ClassDeclaration` (and all the rules
+it contains) has been removed.
+
+Replacing `PSR1.Classes.ClassDeclaration` with just `PSR1` had been possible to
+remove the whole standard, while replacing it with `PSR1.Classes.ClassDeclaration.MultipleClasses`
+only the single rule is removed.
+
+## Remove rules via code comments
+
+If it is necessary to remove a rule/sniff/standard subset/standard only in 
+specific place in the code, it is possible to use special comments that starts
+with:
+
+```php
+// phpcs:disable
+```
+
+followed by the what you want to to remove.
+
+For example: `// phpcs:disable PSR1.Classes.ClassDeclaration`.
+
+From the point the comment is encountered to the end of the file, the requested
+rule/sniff/standard subset/standard is not checked anymore.
+
+To re-enable it is necessary to use a similar syntax, but this time using 
+`phpcs:enable` instead of `phpcs:disable`.
+
+It worth nothing:
+
+- `phpcs:disable` and `phpcs:enable` can be used without anything else, in this
+  case the check for *all* rules are disabled/enabled.
+- Disabling / enabling comments could be embedded in doc block comments at
+  file/class/method level. For example:
+  
+```php
+class Foo
+{
+    /**
+     * @param mixed $a
+     * @param mixed $b
+     *
+     * phpcs:disable NeutronStandard.Functions.TypeHint.NoArgumentType
+     */
+    public function test($a, $b)
+    {
+        // phpcs:enable
+    }
+}
+```
+
+
 -------------
 
+
 # IDE integration
 
 ## PhpStorm
diff --git a/docs/rules-list/custom.md b/docs/rules-list/custom.md
@@ -0,0 +1,18 @@
+# Custom Rules
+
+- CodingStandard
+    - CodingStandard.CodeQuality
+        - CodingStandard.CodeQuality.ElementNameMinimalLength
+            - CodingStandard.CodeQuality.ElementNameMinimalLength.TooShort
+        - CodingStandard.CodeQuality.ForbiddenPublicProperty
+            - CodingStandard.CodeQuality.ForbiddenPublicProperty.Found
+        - CodingStandard.CodeQuality.FunctionLength
+            - CodingStandard.CodeQuality.FunctionLength.TooLong
+        - CodingStandard.CodeQuality.MaxNestingLevel
+            - CodingStandard.CodeQuality.MaxNestingLevel.TooNested
+        - CodingStandard.CodeQuality.NoElse
+            - CodingStandard.CodeQuality.NoElse.NoElse
+        - CodingStandard.CodeQuality.NoSetter
+            - CodingStandard.CodeQuality.NoSetter.NoSetter
+        - CodingStandard.CodeQuality.PropertyPerClassLimit
+            - CodingStandard.CodeQuality.PropertyPerClassLimit.TooMuchProperties
diff --git a/docs/rules-list/generic.md b/docs/rules-list/generic.md
@@ -0,0 +1,54 @@
+# Generic, Squiz and PEAR Rules
+
+- Generic
+    - Generic.ControlStructures
+        - Generic.ControlStructures.InlineControlStructure
+            - Generic.ControlStructures.InlineControlStructure.NotAllowed
+    - Generic.Files
+        - Generic.Files.ByteOrderMark
+            - Generic.Files.ByteOrderMark.Found
+        - Generic.Files.LineEndings
+            - Generic.Files.LineEndings.InvalidEOLChar
+        - Generic.Files.LineLength
+    - Generic.Functions
+        - Generic.FunctionCallArgumentSpacing
+    - Generic.NamingConventions
+        - Generic.NamingConventions.UpperCaseConstantName
+    - Generic.WhiteSpace
+        - Generic.WhiteSpace.SuperfluousWhitespace
+        - Generic.WhiteSpace.ScopeIndent
+        - Generic.WhiteSpace.DisallowTabIndent
+    - Generic.Formatting
+        - Generic.Formatting.DisallowMultipleStatements
+    - Generic.PHP
+        - Generic.PHP.LowerCaseKeyword
+        
+- Squiz
+    - Squiz.Classes
+        - Squiz.Classes.ValidClassName
+    - Squiz.ControlStructures
+        - Squiz.ControlStructures.ControlSignature
+        - Squiz.ControlStructures.ForEachLoopDeclaration
+        - Squiz.ControlStructures.ForLoopDeclaration
+        - Squiz.ControlStructures.LowercaseDeclaration
+        - Squiz.ControlStructures.InlineControlStructure
+    - Squiz.Functions
+        - Squiz.Functions.FunctionDeclaration
+        - Squiz.Functions.LowercaseFunctionKeywords
+        - Squiz.Functions.FunctionDeclarationArgumentSpacing
+        - Squiz.Functions.MultiLineFunctionDeclaration
+    - Squiz.Scope
+        - Squiz.Scope.MethodScope
+    - Squiz.PHP
+        - Squiz.PHP.Eval
+            - Squiz.PHP.Eval.Discouraged
+        - Squiz.PHP.CommentedOutCode
+            - Squiz.PHP.CommentedOutCode.Found
+    - Squiz.WhiteSpace
+        - Squiz.WhiteSpace.ScopeKeywordSpacing
+        - Squiz.WhiteSpace.ControlStructureSpacing
+        - Squiz.WhiteSpace.ScopeClosingBrace
+
+- PEAR
+    - PEAR.Functions
+        - PEAR.Functions.ValidDefaultValue
diff --git a/docs/rules-list/neutron-standard.md b/docs/rules-list/neutron-standard.md
@@ -0,0 +1,40 @@
+# Neutron Standard Rules
+
+- NeutronStandard
+    - NeutronStandard.Arrays
+        - NeutronStandard.Arrays.DisallowLongformArray
+            - NeutronStandard.Arrays.DisallowLongformArray.LongformArray
+    - NeutronStandard.Conditions
+        - NeutronStandard.Conditions.DisallowConditionAssignWithoutConditional
+            - NeutronStandard.Conditions.DisallowConditionAssignWithoutConditional.ConditionAssignWithoutConditional
+    - NeutronStandard.Constants
+        - NeutronStandard.Constants.DisallowDefine
+            - NeutronStandard.Constants.DisallowDefine.Define
+    - NeutronStandard.Extract
+        - NeutronStandard.Extract.DisallowExtract
+            - NeutronStandard.Extract.DisallowExtract.Extract
+    - NeutronStandard.Functions
+        - NeutronStandard.Functions.DisallowCallUserFunc
+            - NeutronStandard.Functions.DisallowCallUserFunc.CallUserFunc
+        - NeutronStandard.Functions.TypeHint
+            - NeutronStandard.Functions.TypeHint.NoArgumentType
+            - NeutronStandard.Functions.TypeHint.UnusedReturnType
+            - NeutronStandard.Functions.TypeHint.IncorrectVoidReturnType
+    - NeutronStandard.Globals
+        - NeutronStandard.Globals.DisallowGlobalFunctions
+            - NeutronStandard.Globals.DisallowGlobalFunctions.GlobalFunctions
+    - NeutronStandard.MagicMethods
+        - NeutronStandard.MagicMethods.DisallowMagicGet
+            - NeutronStandard.MagicMethods.DisallowMagicGet.MagicGet
+        - NeutronStandard.MagicMethods.DisallowMagicSerialize
+            - NeutronStandard.MagicMethods.DisallowMagicSerialize.MagicSerialize
+        - NeutronStandard.MagicMethods.DisallowMagicSet
+            - NeutronStandard.MagicMethods.DisallowMagicSet.MagicSet
+        - NeutronStandard.MagicMethods.RiskyMagicMethod
+            - NeutronStandard.MagicMethods.RiskyMagicMethod.RiskyMagicMethod
+    - NeutronStandard.StrictTypes
+        - NeutronStandard.StrictTypes.RequireStrictTypes
+            - NeutronStandard.StrictTypes.RequireStrictTypes.StrictTypes
+    - NeutronStandard.Whitespace
+        - NeutronStandard.Whitespace.DisallowMultipleNewlines
+            - NeutronStandard.Whitespace.DisallowMultipleNewlines.MultipleNewlines
diff --git a/docs/rules-list/psr.md b/docs/rules-list/psr.md
diff --git a/docs/rules-list/variable-analysis.md b/docs/rules-list/variable-analysis.md
diff --git a/docs/rules-list/wordpress.md b/docs/rules-list/wordpress.md

Original file line number	Diff line number	Diff line change
`@@ -66,7 +66,7 @@ public function process(File $file, $position)`
`66`	`66`	`$this->minLength`
`67`	`67`	`);`
`68`	`68`
`69`		`- $file->addError($message, $position, 'ElementNameMinimalLength');`
	`69`	`+ $file->addError($message, $position, 'TooShort');`
`70`	`70`	`}`
`71`	`71`
`72`	`72`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,7 @@ public function process(File $file, $position)`
`54`	`54`	`$file->addError(`
`55`	`55`	`'Do not use public properties. Use method access instead.',`
`56`	`56`	`$position,`
`57`		`- 'ForbiddenPublicProperty'`
	`57`	`+ 'Found'`
`58`	`58`	`);`
`59`	`59`	`}`
`60`	`60`	`}`
Original file line number	Diff line number	Diff line change
`@@ -52,7 +52,7 @@ public function process(File $file, $position)`
`52`	`52`	`$this->maxLength`
`53`	`53`	`);`
`54`	`54`
`55`		`- $file->addError($error, $position, 'FunctionLength');`
	`55`	`+ $file->addError($error, $position, 'TooLong');`
`56`	`56`	`}`
`57`	`57`	`}`
`58`	`58`
Original file line number	Diff line number	Diff line change
`@@ -105,7 +105,7 @@ private function handleNestingLevel(int $nestingLevel)`
`105`	`105`	`$nestingLevel`
`106`	`106`	`);`
`107`	`107`
`108`		`- $this->file->addError($error, $this->position, 'MaxNestingLevel');`
	`108`	`+ $this->file->addError($error, $this->position, 'TooNested');`
`109`	`109`	`}`
`110`	`110`	`}`
`111`	`111`
Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,7 @@ public function process(File $file, $position)`
`56`	`56`	`$this->maxCount`
`57`	`57`	`);`
`58`	`58`
`59`		`- $file->addWarning($message, $position, 'PropertyPerClassLimit');`
	`59`	`+ $file->addWarning($message, $position, 'TooMuchProperties');`
`60`	`60`	`}`
`61`	`61`	`}`
`62`	`62`	`}`