Docs: improvements for better rendering in PHPDocumentor

* Remove markdown from DocBlock summaries as it's not supported.
* Add backticks around inline code elements in long descriptions and tag descriptions.
* Add markdown where relevant in long descriptions and tag descriptions to improve readability of the rendered output.
* Add inline `{@see ...}` tags to create links to other documented elements.
* Add inline `{@link ...}` tags.
* Replace `<code>` tags with code block syntax.
* Lower the amount of indentation used in code blocks for more readable rendering.
* Replace singular backticks for multi-line code blocks with triple backticks, to allow for rendering as a proper code block instead of inline.
* Replace some semi-lists with list syntax supported via markdown for better rendering.
* Replace some list like return value array definitions with code blocks for better rendering.
* Make some "Note:"  remarks use blockquote syntax to draw more attention to them.
* Use uppercase true/false/null in `@return` tags to make them more easily readable at a glance.

Author: jrfnl

PHPCSUtils/AbstractSniffs/AbstractArrayDeclarationSniff.php

@@ -68,10 +68,14 @@ abstract class AbstractArrayDeclarationSniff implements Sniff
      * A multi-dimentional array with information on each array item.
      *
      * The array index is 1-based and contains the following information on each array item:
-     * - 'start' : The stack pointer to the first token in the array item.
-     * - 'end'   : The stack pointer to the last token in the array item.
-     * - 'raw'   : A string with the contents of all tokens between `start` and `end`.
-     * - 'clean' : Same as `raw`, but all comment tokens have been stripped out.
+     * ```php
+     * 1 => array(
+     *   'start' => int,    // The stack pointer to the first token in the array item.
+     *   'end'   => int,    // The stack pointer to the last token in the array item.
+     *   'raw'   => string, // A string with the contents of all tokens between `start` and `end`.
+     *   'clean' => string, // Same as `raw`, but all comment tokens have been stripped out.
+     * )
+     * ```
      *
      * @since 1.0.0
      *
@@ -163,7 +167,7 @@ public function register()
      * Processes this test when one of its tokens is encountered.
      *
      * This method fills the properties with relevant information for examining the array
-     * and then passes off to the `processArray()` method.
+     * and then passes off to the {@see AbstractArrayDeclarationSniff::processArray()} method.
      *
      * @since 1.0.0
      *
@@ -290,9 +294,9 @@ public function processArray(File $phpcsFile)
      * @param int                         $openPtr   The position of the array opener token in the token stack.
      * @param int                         $closePtr  The position of the array closer token in the token stack.
      *
-     * @return true|void Returning `true` will short-circuit the sniff and stop processing.
+     * @return true|void Returning `TRUE` will short-circuit the sniff and stop processing.
      *                   In effect, this means that the sniff will not examine the individual
-     *                   array items if `true` is returned.
+     *                   array items if `TRUE` is returned.
      */
     public function processOpenClose(File $phpcsFile, $openPtr, $closePtr)
     {
@@ -321,7 +325,7 @@ public function processOpenClose(File $phpcsFile, $openPtr, $closePtr)
      * @param int                         $itemNr    Which item in the array is being handled.
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
-     * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     * @return true|void Returning `TRUE` will short-circuit the array item loop and stop processing.
      *                   In effect, this means that the sniff will not examine the double arrow, the array
      *                   value or comma for this array item and will not process any array items after this one.
      */
@@ -351,7 +355,7 @@ public function processKey(File $phpcsFile, $startPtr, $endPtr, $itemNr)
      * @param int                         $itemNr    Which item in the array is being handled.
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
-     * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     * @return true|void Returning `TRUE` will short-circuit the array item loop and stop processing.
      *                   In effect, this means that the sniff will not examine the array value or
      *                   comma for this array item and will not process any array items after this one.
      */
@@ -374,7 +378,7 @@ public function processNoKey(File $phpcsFile, $startPtr, $itemNr)
      * @param int                         $itemNr    Which item in the array is being handled.
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
-     * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     * @return true|void Returning `TRUE` will short-circuit the array item loop and stop processing.
      *                   In effect, this means that the sniff will not examine the array value or
      *                   comma for this array item and will not process any array items after this one.
      */
@@ -403,7 +407,7 @@ public function processArrow(File $phpcsFile, $arrowPtr, $itemNr)
      * @param int                         $itemNr    Which item in the array is being handled.
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
-     * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     * @return true|void Returning `TRUE` will short-circuit the array item loop and stop processing.
      *                   In effect, this means that the sniff will not examine the comma for this
      *                   array item and will not process any array items after this one.
      */
@@ -426,7 +430,7 @@ public function processValue(File $phpcsFile, $startPtr, $endPtr, $itemNr)
      * @param int                         $itemNr    Which item in the array is being handled.
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
-     * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     * @return true|void Returning `TRUE` will short-circuit the array item loop and stop processing.
      *                   In effect, this means that the sniff will not process any array items
      *                   after this one.
      */