Merge pull request #1587 from WordPress-Coding-Standards/feature/add-some-dev-documentation

Extra: Document why two WPCS native sniffs are not (yet) replaced

Author: GaryJones

WordPress-Extra/ruleset.xml

@@ -27,7 +27,9 @@
 	</rule>
 
 	<!-- Duplicate of upstream. Can be removed once minimum PHPCS requirement has gone up.
-		 https://github.com/squizlabs/PHP_CodeSniffer/pull/1594 -->
+		 https://github.com/squizlabs/PHP_CodeSniffer/pull/1594
+		 Note: the "assignment in ternary" part of the sniff is currently not yet covered in
+		 the upstream version. This needs to be pulled first before we can defer to upstream. -->
 	<rule ref="WordPress.CodeAnalysis.AssignmentInCondition"/>
 
 	<!-- More generic PHP best practices.
@@ -145,7 +147,14 @@
 	<rule ref="WordPress.NamingConventions.PrefixAllGlobals"/>
 
 	<!-- Check that object instantiations always have braces & are not assigned by reference.
-		 https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/919 -->
+		 https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/919
+		 Note: there is a similar upstream sniff `PSR12.Classes.ClassInstantiation`, however
+		 that sniff:
+		 - does not cover JS files;
+		 - does not demand parentheses for PHP anonymous classes;
+		 - does not check the whitespace between the class name and the parentheses;
+		 - does not check for PHP new by reference.
+		 For those reasons, the WPCS version should remain. -->
 	<rule ref="WordPress.Classes.ClassInstantiation"/>
 
 	<!-- https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1157 -->