Coding-Standard-Tutorial: update the tutorial

* Remove mention of creating the standards in the PHPCS `Standards` directory and replace it with information about registering a standard with PHPCS via the `installed_paths` command.
* Add note about the token array containing additional information.
* Modernize the sniff code sample.
    - Replace the file docblock with a simpler class docblock.
    - Use the correct namespace for the standard.
    - Make it a `final` class.
    - Use short arrays.
    - Remove `//end ...` comments.
    - Improve type specificity in the docblocks.
    - Remove PHP close tag.
* Improve the test code by including code samples which should *not* be flagged (but would trigger the sniff).
* Use the more common term (class) "property" instead of "member variable".
* Fix grammatical error.
* Use fenced code blocks for bash commands.
* Various other markdown tweaks for readability.

Author: jrfnl

wiki/Coding-Standard-Tutorial.md

@@ -2,25 +2,29 @@ In this tutorial, we will create a new coding standard with a single sniff. Our
 
 ## Creating the Coding Standard Directory
 
-All sniffs in PHP_CodeSniffer must belong to a coding standard. A coding standard is a directory with a specific sub-directory structure and a ruleset.xml file, so we can create one very easily. Let's call our coding standard _MyStandard_. Run the following commands to create the coding standard directory structure:
+All sniffs in PHP_CodeSniffer must belong to a coding standard. A coding standard is a directory with a specific sub-directory structure and a `ruleset.xml` file, so we can create one very easily. Let's call our coding standard _MyStandard_. Run the following commands to create the coding standard directory structure:
 
-    $ mkdir MyStandard
-    $ mkdir MyStandard/Sniffs
+```bash
+$ mkdir MyStandard
+$ mkdir MyStandard/Sniffs
+```
 
-As this coding standard directory sits outside the main PHP_CodeSniffer directory structure, PHP_CodeSniffer will not show it as an installed standard when using the `-i` command line argument. If you want your standard to be shown as installed, create the MyStandard directory inside the PHP_CodeSniffer install:
+As this coding standard directory sits outside the main PHP_CodeSniffer directory structure, PHP_CodeSniffer will not show it as an installed standard when using the `-i` command line argument. If you want your standard to be shown as installed, [register the MyStandard directory as an external standards with PHP_CodeSniffer](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Configuration-Options#setting-the-installed-standard-paths):
 
-    $ cd /path/to/PHP_CodeSniffer/src/Standards
-    $ mkdir MyStandard
-    $ mkdir MyStandard/Sniffs
+```bash
+$ phpcs --config-set installed_paths /path/to/MyStandard
+```
 
 The `MyStandard` directory represents our coding standard. The `Sniffs` sub-directory is used to store all the sniff files for this coding standard.
 
-Now that our directory structure is created, we need to add our ruleset.xml file. This file will allow PHP_CodeSniffer to ask our coding standard for information about itself, and also identify this directory as one that contains code sniffs.
+Now that our directory structure is created, we need to add our `ruleset.xml` file. This file will allow PHP_CodeSniffer to ask our coding standard for information about itself, and also identify this directory as one that contains code sniffs.
 
-    $ cd MyStandard
-    $ touch ruleset.xml
+```bash
+$ cd MyStandard
+$ touch ruleset.xml
+```
 
-The content of the `ruleset.xml` file should be the following:
+The content of the `ruleset.xml` file should, at a minimum, be the following:
 
 ```xml
 <?xml version="1.0"?>
@@ -30,15 +34,17 @@ The content of the `ruleset.xml` file should be the following:
 ```
 
 > [!NOTE]
-> The ruleset.xml can be left quite small, as it is in this example coding standard. For information about the other features that the ruleset.xml provides, see the [[Annotated ruleset]].
+> The ruleset.xml can be left quite small, as it is in this example coding standard. For information about the other features that the `ruleset.xml` provides, see the [[Annotated ruleset]].
 
 ## Creating the Sniff
 
-A sniff requires a single PHP file that must be placed into a sub-directory to categorise the type of check it performs. It's name should clearly describe the standard that we are enforcing and must end with `Sniff.php`. For our sniff, we will name the PHP file `DisallowHashCommentsSniff.php` and place it into a `Commenting` sub-directory to categorise this sniff as relating to commenting. Run the following commands to create the category and the sniff:
+A sniff requires a single PHP file that must be placed into a sub-directory to categorise the type of check it performs. Its name should clearly describe the standard that we are enforcing and must end with `Sniff.php`. For our sniff, we will name the PHP file `DisallowHashCommentsSniff.php` and place it into a `Commenting` sub-directory to categorise this sniff as relating to commenting. Run the following commands to create the category and the sniff:
 
-    $ cd Sniffs
-    $ mkdir Commenting
-    $ touch Commenting/DisallowHashCommentsSniff.php
+```bash
+$ cd Sniffs
+$ mkdir Commenting
+$ touch Commenting/DisallowHashCommentsSniff.php
+```
 
 > [!NOTE]
 > It does not matter what sub-directories you use for categorising your sniffs. Just make them descriptive enough so you can find your sniffs again later when you want to modify them.
@@ -53,49 +59,43 @@ For our sniff, we are interested in single line comments. The `token_get_all` me
 
 ## The Token Stack
 
-A sniff can gather more information about a token by acquiring the token stack with a call to the `getTokens` method on the `PHP_CodeSniffer\Files\File` object. This method returns an array and is indexed by the position where the token occurs in the token stack. Each element in the array represents a token. All tokens have a `code`, `type` and a `content` index in their array. The `code` value is a unique integer for the type of token. The `type` value is a string representation of the token (e.g., 'T_COMMENT' for comment tokens). The `type` has a corresponding globally defined integer with the same name. Finally, the `content` value contains the content of the token as it appears in the code.
+A sniff can gather more information about a token by acquiring the token stack with a call to the `getTokens` method on the `PHP_CodeSniffer\Files\File` object. This method returns an array and is indexed by the position where the token occurs in the token stack. Each element in the array represents a token. All tokens have a `code`, `type` and a `content` index in their array. The `code` value is a unique integer for the type of token. The `type` value is a string representation of the token (e.g., `'T_COMMENT'` for comment tokens). The `type` has a corresponding globally defined integer with the same name. Finally, the `content` value contains the content of the token as it appears in the code.
+
+> [!NOTE]
+> Depending on the token, the token array may contain various additional indexes with further information on a token.
 
 ## Reporting Errors
 
-Once an error is detected, a sniff should indicate that an error has occurred by calling the `addError` method on the `PHP_CodeSniffer\Files\File` object, passing in an appropriate error message as the first argument, the position in the stack where the error was detected as the second, a code to uniquely identify the error within this sniff and an array of data used inside the error message. Alternatively, if the violation is considered not as critical as an error, the `addWarning` method can be used.
+Once an error is detected, a sniff should indicate that an error has occurred by calling the `addError` method on the `PHP_CodeSniffer\Files\File` object, passing in an appropriate error message as the first argument, the position in the stack where the error was detected as the second, a code to uniquely identify the error within this sniff and an array of data used inside the error message.
+Alternatively, if the violation is considered not as critical as an error, the `addWarning` method can be used.
 
 ## DisallowHashCommentsSniff.php
 
 We now have to write the content of our sniff. The content of the `DisallowHashCommentsSniff.php` file should be the following:
 
 ```php
 <?php
-/**
- * This sniff prohibits the use of Perl style hash comments.
- *
- * PHP version 5
- *
- * @category  PHP
- * @package   PHP_CodeSniffer
- * @author    Your Name <you@domain.net>
- * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
- */
 
-namespace PHP_CodeSniffer\Standards\MyStandard\Sniffs\Commenting;
+namespace MyStandard\Sniffs\Commenting;
 
 use PHP_CodeSniffer\Sniffs\Sniff;
 use PHP_CodeSniffer\Files\File;
 
-class DisallowHashCommentsSniff implements Sniff
+/**
+ * This sniff prohibits the use of Perl style hash comments.
+ */
+final class DisallowHashCommentsSniff implements Sniff
 {
 
-
     /**
      * Returns the token types that this sniff is interested in.
      *
-     * @return array(int)
+     * @return array<int|string>
      */
     public function register()
     {
-        return array(T_COMMENT);
-
-    }//end register()
-
+        return [T_COMMENT];
+    }
 
     /**
      * Processes this sniff, when one of its tokens is encountered.
@@ -111,30 +111,25 @@ class DisallowHashCommentsSniff implements Sniff
         $tokens = $phpcsFile->getTokens();
         if ($tokens[$stackPtr]['content'][0] === '#') {
             $error = 'Hash comments are prohibited; found %s';
-            $data  = array(trim($tokens[$stackPtr]['content']));
+            $data  = [trim($tokens[$stackPtr]['content'])];
             $phpcsFile->addError($error, $stackPtr, 'Found', $data);
         }
-
-    }//end process()
-
-
-}//end class
-
-?>
+    }
+}
 ```
 
-By default, PHP_CodeSniffer assumes all sniffs are designed to check PHP code only. You can specify a list of tokenizers that your sniff supports, allowing it to be used wth PHP, JavaScript or CSS files, or any combination of the three. You do this by setting the `$supportedTokenizers` member variable in your sniff. Adding the following code to your sniff will tell PHP_CodeSniffer that it can be used to check both PHP and JavaScript code:
+By default, PHP_CodeSniffer assumes all sniffs are designed to check PHP code only. You can specify a list of tokenizers that your sniff supports, allowing it to be used wth PHP, JavaScript or CSS files, or any combination of the three. You do this by setting the `$supportedTokenizers` property in your sniff. Adding the following code to your sniff will tell PHP_CodeSniffer that it can be used to check both PHP and JavaScript code:
 
 ```php
 /**
  * A list of tokenizers this sniff supports.
  *
- * @var array
+ * @var array<string>
  */
-public $supportedTokenizers = array(
+public $supportedTokenizers = [
     'PHP',
     'JS',
-);
+];
 ```
 
 
@@ -145,7 +140,11 @@ Now that we have defined a coding standard, let's validate a file that contains
 ```php
 <?php
 
-# Check for valid contents.
+// Slash comments should be ignored.
+
+/* Star comments should also be ignored. */
+
+# Hash comments should be flagged.
 if ($obj->contentsAreValid($array)) {
     $value = $obj->getValue();
 
@@ -156,23 +155,18 @@ if ($obj->contentsAreValid($array)) {
         exit();
     }
 }
-
-?>
 ```
 
 When PHP_CodeSniffer is run on the file using our new coding standard, 3 errors will be reported:
-
-    $ phpcs --standard=/path/to/MyStandard test.php
-
-    FILE: test.php
-    --------------------------------------------------------------------------------
-    FOUND 3 ERROR(S) AFFECTING 3 LINE(S)
-    --------------------------------------------------------------------------------
-     3 | ERROR | Hash comments are prohibited; found # Check for valid contents.
-     7 | ERROR | Hash comments are prohibited; found # Value needs to be an array.
-     9 | ERROR | Hash comments are prohibited; found # Error.
-    --------------------------------------------------------------------------------
-
-Note that we pass the absolute path to our coding standard directory on the command line because our standard is not installed inside the main PHP_CodeSniffer directory structure. If you have created your standard inside PHP_CodeSniffer, you can simply pass the name of the standard:
-
-    $ phpcs --standard=MyStandard Test.php
+```bash
+$ phpcs --standard=MyStandard test.php
+
+FILE: test.php
+--------------------------------------------------------------------------------
+FOUND 3 ERROR(S) AFFECTING 3 LINE(S)
+--------------------------------------------------------------------------------
+  7 | ERROR | Hash comments are prohibited; found # Hash comments should be flagged.
+ 11 | ERROR | Hash comments are prohibited; found # Value needs to be an array.
+ 13 | ERROR | Hash comments are prohibited; found # Error.
+--------------------------------------------------------------------------------
+```