Normalize PHPDoc comments

Author: tgalopin

.php_cs.dist

@@ -8,6 +8,7 @@ return PhpCsFixer\Config::create()
     ->setRules(array(
         '@Symfony' => true,
         'concat_space' => array('spacing' => 'one'),
+        'phpdoc_annotation_without_dot' => false,
     ))
     ->setFinder($finder)
 ;

.travis.yml

@@ -30,7 +30,7 @@ before_script:
 
 script:
   - stty cols 120
-  - if [ "$CS_FIXER" == 1 ]; then wget https://github.com/FriendsOfPHP/PHP-CS-Fixer/releases/download/v2.13.1/php-cs-fixer.phar && php php-cs-fixer.phar fix . --dry-run --diff --rules="@Symfony"; fi
+  - if [ "$CS_FIXER" == 1 ]; then wget https://github.com/FriendsOfPHP/PHP-CS-Fixer/releases/download/v2.13.1/php-cs-fixer.phar && php php-cs-fixer.phar fix --dry-run --diff; fi
   - mkdir -p build/logs
   - ./vendor/bin/phpunit --coverage-clover=coverage.xml
 

src/HTML5.php

@@ -57,7 +57,7 @@ public function getOptions()
      * @param string|resource $file    The path to the file to parse. If this is a resource, it is
      *                                 assumed to be an open stream whose pointer is set to the first
      *                                 byte of input.
-     * @param array           $options Configuration options when parsing the HTML
+     * @param array           $options Configuration options when parsing the HTML.
      *
      * @return \DOMDocument A DOM document. These object type is defined by the libxml
      *                      library, and should have been included with your version of PHP.
@@ -78,8 +78,8 @@ public function load($file, array $options = array())
      * Take a string of HTML 5 (or earlier) and parse it into a
      * DOMDocument.
      *
-     * @param string $string  A html5 document as a string
-     * @param array  $options Configuration options when parsing the HTML
+     * @param string $string  A html5 document as a string.
+     * @param array  $options Configuration options when parsing the HTML.
      *
      * @return \DOMDocument A DOM document. DOM is part of libxml, which is included with
      *                      almost all distribtions of PHP.
@@ -98,7 +98,7 @@ public function loadHTML($string, array $options = array())
      * @param string $file    The path to the file to parse. If this is a resource, it is
      *                        assumed to be an open stream whose pointer is set to the first
      *                        byte of input.
-     * @param array  $options Configuration options when parsing the HTML
+     * @param array  $options Configuration options when parsing the HTML.
      *
      * @return \DOMDocument A DOM document. These object type is defined by the libxml
      *                      library, and should have been included with your version of PHP.
@@ -170,8 +170,8 @@ public function parse($input, array $options = array())
      * Lower-level loading function. This requires an input stream instead
      * of a string, file, or resource.
      *
-     * @param string $input   the input data to parse in the form of a string
-     * @param array  $options An array of options
+     * @param string $input   The input data to parse in the form of a string.
+     * @param array  $options An array of options.
      *
      * @return \DOMDocumentFragment
      */
@@ -191,8 +191,8 @@ public function parseFragment($input, array $options = array())
     /**
      * Save a DOM into a given file as HTML5.
      *
-     * @param mixed           $dom     The DOM to be serialized
-     * @param string|resource $file    The filename to be written or resource to write to
+     * @param mixed           $dom     The DOM to be serialized.
+     * @param string|resource $file    The filename to be written or resource to write to.
      * @param array           $options Configuration options when serializing the DOM. These include:
      *                                 - encode_entities: Text written to the output is escaped by default and not all
      *                                 entities are encoded. If this is set to true all entities will be encoded.
@@ -221,13 +221,13 @@ public function save($dom, $file, $options = array())
     /**
      * Convert a DOM into an HTML5 string.
      *
-     * @param mixed $dom     The DOM to be serialized
+     * @param mixed $dom     The DOM to be serialized.
      * @param array $options Configuration options when serializing the DOM. These include:
      *                       - encode_entities: Text written to the output is escaped by default and not all
      *                       entities are encoded. If this is set to true all entities will be encoded.
      *                       Defaults to false.
      *
-     * @return string a HTML5 documented generated from the DOM
+     * @return string A HTML5 documented generated from the DOM.
      */
     public function saveHTML($dom, $options = array())
     {

src/HTML5/Elements.php

@@ -477,10 +477,10 @@ class Elements
      *
      * Elements::isA('script', Elements::TEXT_RCDATA); // Returns false.
      *
-     * @param string $name The element name
-     * @param int    $mask One of the constants on this class
+     * @param string $name The element name.
+     * @param int    $mask One of the constants on this class.
      *
-     * @return bool true if the element matches the mask, false otherwise
+     * @return bool true if the element matches the mask, false otherwise.
      */
     public static function isA($name, $mask)
     {
@@ -490,9 +490,9 @@ public static function isA($name, $mask)
     /**
      * Test if an element is a valid html5 element.
      *
-     * @param string $name The name of the element
+     * @param string $name The name of the element.
      *
-     * @return bool true if a html5 element and false otherwise
+     * @return bool true if a html5 element and false otherwise.
      */
     public static function isHtml5Element($name)
     {
@@ -504,9 +504,9 @@ public static function isHtml5Element($name)
     /**
      * Test if an element name is a valid MathML presentation element.
      *
-     * @param string $name The name of the element
+     * @param string $name The name of the element.
      *
-     * @return bool true if a MathML name and false otherwise
+     * @return bool true if a MathML name and false otherwise.
      */
     public static function isMathMLElement($name)
     {
@@ -517,9 +517,9 @@ public static function isMathMLElement($name)
     /**
      * Test if an element is a valid SVG element.
      *
-     * @param string $name The name of the element
+     * @param string $name The name of the element.
      *
-     * @return bool true if a SVG element and false otherise
+     * @return bool true if a SVG element and false otherise.
      */
     public static function isSvgElement($name)
     {
@@ -529,13 +529,12 @@ public static function isSvgElement($name)
 
     /**
      * Is an element name valid in an html5 document.
-     *
      * This includes html5 elements along with other allowed embedded content
      * such as svg and mathml.
      *
-     * @param string $name The name of the element
+     * @param string $name The name of the element.
      *
-     * @return bool true if valid and false otherwise
+     * @return bool true if valid and false otherwise.
      */
     public static function isElement($name)
     {
@@ -545,9 +544,9 @@ public static function isElement($name)
     /**
      * Get the element mask for the given element name.
      *
-     * @param string $name The name of the element
+     * @param string $name The name of the element.
      *
-     * @return int the element mask
+     * @return int the element mask.
      */
     public static function element($name)
     {
@@ -567,9 +566,9 @@ public static function element($name)
     /**
      * Normalize a SVG element name to its proper case and form.
      *
-     * @param string $name The name of the element
+     * @param string $name The name of the element.
      *
-     * @return string the normalized form of the element name
+     * @return string the normalized form of the element name.
      */
     public static function normalizeSvgElement($name)
     {
@@ -584,9 +583,9 @@ public static function normalizeSvgElement($name)
     /**
      * Normalize a SVG attribute name to its proper case and form.
      *
-     * @param string $name The name of the attribute
+     * @param string $name The name of the attribute.
      *
-     * @return string the normalized form of the attribute name
+     * @return string The normalized form of the attribute name.
      */
     public static function normalizeSvgAttribute($name)
     {
@@ -600,12 +599,11 @@ public static function normalizeSvgAttribute($name)
 
     /**
      * Normalize a MathML attribute name to its proper case and form.
-     *
      * Note, all MathML element names are lowercase.
      *
-     * @param string $name The name of the attribute
+     * @param string $name The name of the attribute.
      *
-     * @return string the normalized form of the attribute name
+     * @return string The normalized form of the attribute name.
      */
     public static function normalizeMathMlAttribute($name)
     {

src/HTML5/InstructionProcessor.php

@@ -28,9 +28,9 @@ interface InstructionProcessor
      * - Making any subsequent modifications to the DOM by modifying the
      * DOMElement or its attached DOM tree.
      *
-     * @param \DOMElement $element The parent element for the current processing instruction
+     * @param \DOMElement $element The parent element for the current processing instruction.
      * @param string      $name    The instruction's name. E.g. `<?php` has the name `php`.
-     * @param string      $data    All of the data between the opening and closing PI marks
+     * @param string      $data    All of the data between the opening and closing PI marks.
      *
      * @return \DOMElement The element that should be considered "Current". This may just be
      *                     the element passed in, but if the processor added more elements,

src/HTML5/Parser/CharacterReference.php

@@ -21,7 +21,7 @@ class CharacterReference
     /**
      * Given a name (e.g. 'amp'), lookup the UTF-8 character ('&').
      *
-     * @param string $name The name to look up
+     * @param string $name The name to look up.
      *
      * @return string The character sequence. In UTF-8 this may be more than one byte.
      */

src/HTML5/Parser/DOMTreeBuilder.php

@@ -626,19 +626,18 @@ public function processingInstruction($name, $data = null)
 
     /**
      * Apply normalization rules to a tag name.
-     *
      * See sections 2.9 and 8.1.2.
      *
-     * @param string $name The tag name
+     * @param string $tagName
      *
-     * @return string the normalized tag name
+     * @return string The normalized tag name.
      */
-    protected function normalizeTagName($name)
+    protected function normalizeTagName($tagName)
     {
         /*
          * Section 2.9 suggests that we should not do this. if (strpos($name, ':') !== false) { // We know from the grammar that there must be at least one other // char besides :, since : is not a legal tag start. $parts = explode(':', $name); return array_pop($parts); }
          */
-        return $name;
+        return $tagName;
     }
 
     protected function quirksTreeResolver($name)

src/HTML5/Parser/EventHandler.php

@@ -30,11 +30,11 @@ interface EventHandler
     /**
      * A doctype declaration.
      *
-     * @param string $name   The name of the root element
+     * @param string $name   The name of the root element.
      * @param int    $idType One of DOCTYPE_NONE, DOCTYPE_PUBLIC, or DOCTYPE_SYSTEM
      * @param string $id     The identifier. For DOCTYPE_PUBLIC, this is the public ID. If DOCTYPE_SYSTEM,
      *                       then this is a system ID.
-     * @param bool   $quirks Indicates whether the builder should enter quirks mode
+     * @param bool   $quirks Indicates whether the builder should enter quirks mode.
      */
     public function doctype($name, $idType = 0, $id = null, $quirks = false);
 
@@ -59,9 +59,9 @@ public function doctype($name, $idType = 0, $id = null, $quirks = false);
      * The textmode is automatically reset to Tokenizer::TEXTMODE_NORMAL when the
      * closing tag is encounter. **This behavior may change.**
      *
-     * @param string $name        The tag name
-     * @param array  $attributes  An array with all of the tag's attributes
-     * @param bool   $selfClosing An indicator of whether or not this tag is self-closing (<foo/>)
+     * @param string $name        The tag name.
+     * @param array  $attributes  An array with all of the tag's attributes.
+     * @param bool   $selfClosing An indicator of whether or not this tag is self-closing (<foo/>).
      *
      * @return int one of the Tokenizer::TEXTMODE_* constants
      */
@@ -108,7 +108,7 @@ public function cdata($data);
      * While user agents don't get PIs, server-side does.
      *
      * @param string $name The name of the processor (e.g. 'php').
-     * @param string $data The unparsed data
+     * @param string $data The unparsed data.
      */
     public function processingInstruction($name, $data = null);
 }

src/HTML5/Parser/FileInputStream.php

@@ -19,9 +19,9 @@ class FileInputStream extends StringInputStream implements InputStream
     /**
      * Load a file input stream.
      *
-     * @param string $data     the file or url path to load
-     * @param string $encoding the encoding to use for the data
-     * @param string $debug    a fprintf format to use to echo the data on stdout
+     * @param string $data     The file or url path to load.
+     * @param string $encoding The encoding to use for the data.
+     * @param string $debug    A fprintf format to use to echo the data on stdout.
      */
     public function __construct($data, $encoding = 'UTF-8', $debug = '')
     {

src/HTML5/Parser/InputStream.php

@@ -29,7 +29,7 @@ public function currentLine();
      *
      * @TODO Move this to the scanner.
      *
-     * @return int the column number
+     * @return int The column number.
      */
     public function columnOffset();
 
@@ -50,8 +50,8 @@ public function remainingChars();
      *
      * @see strcspn
      *
-     * @param string $bytes Bytes to match
-     * @param int    $max   Maximum number of bytes to scan
+     * @param string $bytes Bytes to match.
+     * @param int    $max   Maximum number of bytes to scan.
      *
      * @return mixed Index or false if no match is found. You should use strong
      *               equality when checking the result, since index could be 0.
@@ -69,14 +69,14 @@ public function charsUntil($bytes, $max = null);
      * @param string $bytes A mask of bytes to match. If ANY byte in this mask matches the
      *                      current char, the pointer advances and the char is part of the
      *                      substring.
-     * @param int    $max   The max number of chars to read
+     * @param int    $max   The max number of chars to read.
      */
     public function charsWhile($bytes, $max = null);
 
     /**
      * Unconsume one character.
      *
-     * @param int $howMany The number of characters to move the pointer back
+     * @param int $howMany The number of characters to move the pointer back.
      */
     public function unconsume($howMany = 1);