Documentation fixes.

* Added generic file docblock to sniff files which didn't have one.
* Added/replaced generic file docblock for all unit test files.
* Use `@link` rather than `@see` for links to external documentation about a sniff in the file/class docblock.
* Consistent placement of the `@link` tag if available and pointing to WPCS relevant info.
* Removed `PHP version 5` notes. No longer relevant.
* Fixed a few class description referring to the wrong rule/sniff.

Docs still need a lot of love to get up to scratch properly.

WordPress/Sniff.php

@@ -2,8 +2,6 @@
 /**
  * Represents a PHP_CodeSniffer sniff for sniffing WordPress coding standards.
  *
- * PHP version 5
- *
  * @category  PHP
  * @package   PHP_CodeSniffer
  */

WordPress/Sniffs/Arrays/ArrayAssignmentRestrictionsSniff.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * Restricts array assignment of certain keys.
  *

WordPress/Sniffs/Arrays/ArrayDeclarationSniff.php

@@ -2,8 +2,6 @@
 /**
  * Enforces WordPress array format, based upon Squiz code.
  *
- * PHP version 5
- *
  * @category PHP
  * @package  PHP_CodeSniffer
  * @author   John Godley <[email protected]>

WordPress/Sniffs/Arrays/ArrayKeySpacingRestrictionsSniff.php

@@ -1,8 +1,16 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * Check for proper spacing in array key references.
  *
- * @see http://make.wordpress.org/core/handbook/coding-standards/php/#space-usage
+ * @link     http://make.wordpress.org/core/handbook/coding-standards/php/#space-usage
  *
  * @category PHP
  * @package  PHP_CodeSniffer

WordPress/Sniffs/CSRF/NonceVerificationSniff.php

@@ -2,8 +2,6 @@
 /**
  * WordPress_Sniffs_CSRF_NonceVerificationSniff.
  *
- * PHP version 5
- *
  * @since 0.5.0
  *
  * @category PHP
@@ -13,12 +11,13 @@
 /**
  * Checks that nonce verification accompanies form processing.
  *
- * @since 0.5.0
+ * @link     https://developer.wordpress.org/plugins/security/nonces/ Nonces on Plugin Developer Handbook
+ *
+ * @since    0.5.0
  *
  * @category PHP
  * @package  PHP_CodeSniffer
  * @author   J.D. Grimes <[email protected]>
- * @link     https://developer.wordpress.org/plugins/security/nonces/ Nonces on Plugin Developer Handbook
  */
 class WordPress_Sniffs_CSRF_NonceVerificationSniff extends WordPress_Sniff {
 

WordPress/Sniffs/Classes/ValidClassNameSniff.php

@@ -2,8 +2,6 @@
 /**
  * Modified Squiz_Sniffs_Classes_ValidClassNameSniff.
  *
- * PHP version 5
- *
  * @category  PHP
  * @package   PHP_CodeSniffer
  * @author    Greg Sherwood <[email protected]>

WordPress/Sniffs/Files/FileNameSniff.php

@@ -2,12 +2,9 @@
 /**
  * WordPress Coding Standard.
  *
- * PHP version 5
- *
  * @category PHP
  * @package  PHP_CodeSniffer
- * @author   John Godley
- * @link     http://codex.wordpress.org/WordPress_Coding_Standards
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
  */
 
 /**

WordPress/Sniffs/Functions/FunctionRestrictionsSniff.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * Restricts usage of some functions.
  *

WordPress/Sniffs/NamingConventions/ValidFunctionNameSniff.php

@@ -2,15 +2,13 @@
 /**
  * Enforces WordPress function name format, based upon Squiz code.
  *
- * PHP version 5
- *
  * @category PHP
  * @package  PHP_CodeSniffer
  * @author   John Godley <[email protected]>
  */
 
 /**
- * Enforces WordPress array format.
+ * Enforces WordPress function name format.
  *
  * @category PHP
  * @package  PHP_CodeSniffer

WordPress/Sniffs/PHP/DiscouragedFunctionsSniff.php

@@ -2,8 +2,6 @@
 /**
  * WordPress_Sniffs_PHP_DiscouragedFunctionsSniff.
  *
- * PHP version 5
- *
  * @category PHP
  * @package  PHP_CodeSniffer
  * @author   John Godley <[email protected]>

WordPress/Sniffs/PHP/StrictComparisonsSniff.php

@@ -1,8 +1,14 @@
 <?php
 /**
- * Enforces Strict Comparison checks, based upon Squiz code.
+ * WordPress Coding Standard.
  *
- * PHP version 5
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
+/**
+ * Enforces Strict Comparison checks, based upon Squiz code.
  *
  * @category PHP
  * @package  PHP_CodeSniffer

WordPress/Sniffs/PHP/StrictInArraySniff.php

@@ -1,8 +1,17 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * Flag calling in_array() without true as the third parameter.
  *
- * @link https://vip.wordpress.com/documentation/code-review-what-we-look-for/#using-in_array-without-strict-parameter
+ * @link     https://vip.wordpress.com/documentation/code-review-what-we-look-for/#using-in_array-without-strict-parameter
+ *
  * @category PHP
  * @package  PHP_CodeSniffer
  */

WordPress/Sniffs/PHP/YodaConditionsSniff.php

@@ -2,15 +2,13 @@
 /**
  * Enforces Yoda conditional statements , based upon Squiz code.
  *
- * PHP version 5
- *
  * @category PHP
  * @package  PHP_CodeSniffer
  * @author   Matt Robinson
  */
 
 /**
- * Squiz_Sniffs.
+ * Enforces Yoda conditional statements.
  *
  * @category PHP
  * @package  PHP_CodeSniffer

WordPress/Sniffs/VIP/AdminBarRemovalSniff.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * Discourages removal of the admin bar.
  *

WordPress/Sniffs/VIP/CronIntervalSniff.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * Flag cron schedules less than 15 minutes.
  *

WordPress/Sniffs/VIP/DirectDatabaseQuerySniff.php

@@ -1,13 +1,20 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * Flag Database direct queries.
  *
- * PHP version 5
+ * @link     https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/69
  *
  * @category PHP
  * @package  PHP_CodeSniffer
  * @author   Shady Sharaf <[email protected]>
- * @link     https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/69
  */
 class WordPress_Sniffs_VIP_DirectDatabaseQuerySniff implements PHP_CodeSniffer_Sniff {
 

WordPress/Sniffs/VIP/FileSystemWritesDisallowSniff.php

@@ -1,13 +1,20 @@
 <?php
 /**
- * Disallow Filesystem writes
+ * WordPress Coding Standard.
  *
- * PHP version 5
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
+/**
+ * Disallow Filesystem writes.
+ *
+ * @link     https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/69
  *
  * @category PHP
  * @package  PHP_CodeSniffer
  * @author   Shady Sharaf <[email protected]>
- * @link     https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/69
  */
 class WordPress_Sniffs_VIP_FileSystemWritesDisallowSniff extends Generic_Sniffs_PHP_ForbiddenFunctionsSniff {
 

WordPress/Sniffs/VIP/OrderByRandSniff.php

@@ -1,8 +1,17 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * Flag using orderby => rand.
  *
- * @link https://vip.wordpress.com/documentation/code-review-what-we-look-for/#order-by-rand
+ * @link     https://vip.wordpress.com/documentation/code-review-what-we-look-for/#order-by-rand
+ *
  * @category PHP
  * @package  PHP_CodeSniffer
  */

WordPress/Sniffs/VIP/PluginMenuSlugSniff.php

@@ -1,6 +1,14 @@
 <?php
 /**
- * Warn about __FILE__ for page registration
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
+/**
+ * Warn about __FILE__ for page registration.
  *
  * @category PHP
  * @package  PHP_CodeSniffer

WordPress/Sniffs/VIP/PostsPerPageSniff.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * Flag returning high or infinite posts_per_page.
  *

WordPress/Sniffs/VIP/RestrictedFunctionsSniff.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * Restricts usage of some functions in VIP context.
  *

WordPress/Sniffs/VIP/RestrictedVariablesSniff.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * Restricts usage of some variables in VIP context.
  *

WordPress/Sniffs/VIP/SessionFunctionsUsageSniff.php

@@ -1,13 +1,22 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * WordPress_Sniffs_VIP_SessionFunctionsUsageSniff.
  *
  * Discourages the use of session functions.
  *
+ * @link     https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/75
+ *
  * @category PHP
  * @package  PHP_CodeSniffer
  * @author   Shady Sharaf <[email protected]>
- * @see  https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/75
  */
 class WordPress_Sniffs_VIP_SessionFunctionsUsageSniff extends Generic_Sniffs_PHP_ForbiddenFunctionsSniff {
 

WordPress/Sniffs/VIP/SessionVariableUsageSniff.php

@@ -1,14 +1,23 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * WordPress_Sniffs_VIP_SessionVariableUsageSniff
  *
  * Discourages the use of the session variable.
  * Creating a session writes a file to the server and is unreliable in a multi-server environment.
  *
+ * @link     https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/75
+ *
  * @category PHP
  * @package  PHP_CodeSniffer
  * @author   Shady Sharaf <[email protected]>
- * @link     https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/75
  */
 class WordPress_Sniffs_VIP_SessionVariableUsageSniff extends Generic_Sniffs_PHP_ForbiddenFunctionsSniff {
 

WordPress/Sniffs/VIP/SlowDBQuerySniff.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @category PHP
+ * @package  PHP_CodeSniffer
+ * @link     https://make.wordpress.org/core/handbook/best-practices/coding-standards/
+ */
+
 /**
  * Flag slow queries.
  *