Normalize PHPDoc comments

10 files changed, 64 insertions, 78 deletions

diff --git a/src/HTML5/Parser/CharacterReference.php b/src/HTML5/Parser/CharacterReference.php
index 3ecfba4..490b548 100644
--- a/src/HTML5/Parser/CharacterReference.php
+++ b/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.
      */
diff --git a/src/HTML5/Parser/DOMTreeBuilder.php b/src/HTML5/Parser/DOMTreeBuilder.php
index 365bb75..f01cf4d 100644
--- a/src/HTML5/Parser/DOMTreeBuilder.php
+++ b/src/HTML5/Parser/DOMTreeBuilder.php
@@ -626,19 +626,18 @@ class DOMTreeBuilder implements EventHandler
 
     /**
      * 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)
diff --git a/src/HTML5/Parser/EventHandler.php b/src/HTML5/Parser/EventHandler.php
index cb0109b..9893a71 100644
--- a/src/HTML5/Parser/EventHandler.php
+++ b/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 @@ interface EventHandler
      * 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 @@ interface EventHandler
      * 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);
 }
diff --git a/src/HTML5/Parser/FileInputStream.php b/src/HTML5/Parser/FileInputStream.php
index f176422..b081ed9 100644
--- a/src/HTML5/Parser/FileInputStream.php
+++ b/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 = '')
     {
diff --git a/src/HTML5/Parser/InputStream.php b/src/HTML5/Parser/InputStream.php
index cf279d8..ff4ef22 100644
--- a/src/HTML5/Parser/InputStream.php
+++ b/src/HTML5/Parser/InputStream.php
@@ -29,7 +29,7 @@ interface InputStream extends \Iterator
      *
      * @TODO Move this to the scanner.
      *
-     * @return int the column number
+     * @return int The column number.
      */
     public function columnOffset();
 
@@ -50,8 +50,8 @@ interface InputStream extends \Iterator
      *
      * @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 @@ interface InputStream extends \Iterator
      * @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);
 
diff --git a/src/HTML5/Parser/Scanner.php b/src/HTML5/Parser/Scanner.php
index 7bea1ae..1b52983 100644
--- a/src/HTML5/Parser/Scanner.php
+++ b/src/HTML5/Parser/Scanner.php
@@ -36,10 +36,10 @@ class Scanner
     /**
      * Create a new Scanner.
      *
-     * @param string $data     Data to parse
-     * @param string $encoding the encoding to use for the data
+     * @param string $data     Data to parse.
+     * @param string $encoding The encoding to use for the data.
      *
-     * @throws Exception if the given data cannot be encoded to UTF-8
+     * @throws Exception If the given data cannot be encoded to UTF-8.
      */
     public function __construct($data, $encoding = 'UTF-8')
     {
@@ -90,7 +90,7 @@ class Scanner
     /**
      * Get the current position.
      *
-     * @return int the current intiger byte position
+     * @return int The current intiger byte position.
      */
     public function position()
     {
@@ -100,7 +100,7 @@ class Scanner
     /**
      * Take a peek at the next character in the data.
      *
-     * @return string the next character
+     * @return string The next character.
      */
     public function peek()
     {
@@ -113,10 +113,9 @@ class Scanner
 
     /**
      * Get the next character.
-     *
      * Note: This advances the pointer.
      *
-     * @return string the next character
+     * @return string The next character.
      */
     public function next()
     {
@@ -131,10 +130,9 @@ class Scanner
 
     /**
      * Get the current character.
-     *
      * Note, this does not advance the pointer.
      *
-     * @return string the current character
+     * @return string The current character.
      */
     public function current()
     {
@@ -159,7 +157,7 @@ class Scanner
      * Unconsume some of the data.
      * This moves the data pointer backwards.
      *
-     * @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)
     {
@@ -170,11 +168,10 @@ class Scanner
 
     /**
      * Get the next group of that contains hex characters.
-     *
      * Note, along with getting the characters the pointer in the data will be
      * moved as well.
      *
-     * @return string the next group that is hex characters
+     * @return string The next group that is hex characters.
      */
     public function getHex()
     {
@@ -183,11 +180,10 @@ class Scanner
 
     /**
      * Get the next group of characters that are ASCII Alpha characters.
-     *
      * Note, along with getting the characters the pointer in the data will be
      * moved as well.
      *
-     * @return string the next group of ASCII alpha characters
+     * @return string The next group of ASCII alpha characters.
      */
     public function getAsciiAlpha()
     {
@@ -196,11 +192,10 @@ class Scanner
 
     /**
      * Get the next group of characters that are ASCII Alpha characters and numbers.
-     *
      * Note, along with getting the characters the pointer in the data will be
      * moved as well.
      *
-     * @return string the next group of ASCII alpha characters and numbers
+     * @return string The next group of ASCII alpha characters and numbers.
      */
     public function getAsciiAlphaNum()
     {
@@ -209,11 +204,10 @@ class Scanner
 
     /**
      * Get the next group of numbers.
-     *
      * Note, along with getting the characters the pointer in the data will be
      * moved as well.
      *
-     * @return string the next group of numbers
+     * @return string The next group of numbers.
      */
     public function getNumeric()
     {
@@ -222,10 +216,9 @@ class Scanner
 
     /**
      * Consume whitespace.
-     *
      * Whitespace in HTML5 is: formfeed, tab, newline, space.
      *
-     * @return int The length of the matched whitespaces
+     * @return int The length of the matched whitespaces.
      */
     public function whitespace()
     {
@@ -243,7 +236,7 @@ class Scanner
     /**
      * Returns the current line that is being consumed.
      *
-     * @return int the current line number
+     * @return int The current line number.
      */
     public function currentLine()
     {
@@ -285,7 +278,7 @@ class Scanner
      *
      * Newlines are column 0. The first char after a newline is column 1.
      *
-     * @return int the column number
+     * @return int The column number.
      */
     public function columnOffset()
     {
@@ -319,7 +312,7 @@ class Scanner
      *
      * This consumes characters until the EOF.
      *
-     * @return int the number of characters remaining
+     * @return int The number of characters remaining.
      */
     public function remainingChars()
     {
@@ -366,8 +359,8 @@ class Scanner
      * Matches as far as possible until we reach a certain set of bytes
      * and returns the matched substring.
      *
-     * @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.
@@ -399,7 +392,7 @@ class Scanner
      * @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.
      *
      * @return string
      */
diff --git a/src/HTML5/Parser/StringInputStream.php b/src/HTML5/Parser/StringInputStream.php
index 2281990..0c213fe 100644
--- a/src/HTML5/Parser/StringInputStream.php
+++ b/src/HTML5/Parser/StringInputStream.php
@@ -68,9 +68,9 @@ class StringInputStream implements InputStream
     /**
      * Create a new InputStream wrapper.
      *
-     * @param string $data     Data to parse
-     * @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     Data to parse.
+     * @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 = '')
     {
@@ -140,10 +140,9 @@ class StringInputStream implements InputStream
 
     /**
      * Returns the current column of the current line that the tokenizer is at.
-     *
      * Newlines are column 0. The first char after a newline is column 1.
      *
-     * @return int the column number
+     * @return int The column number.
      */
     public function columnOffset()
     {
@@ -182,7 +181,7 @@ class StringInputStream implements InputStream
     /**
      * Get the current character.
      *
-     * @return string the current character
+     * @return string The current character.
      */
     public function current()
     {
@@ -209,7 +208,7 @@ class StringInputStream implements InputStream
     /**
      * Is the current pointer location valid.
      *
-     * @return bool is the current pointer location valid
+     * @return bool Whether the current pointer location is valid.
      */
     public function valid()
     {
@@ -222,7 +221,7 @@ class StringInputStream implements InputStream
      * This reads to the end of the file, and sets the read marker at the
      * end of the file.
      *
-     * @note This performs bounds checking
+     * Note this performs bounds checking.
      *
      * @return string Returns the remaining text. If called when the InputStream is
      *                already exhausted, it returns an empty string.
@@ -247,8 +246,8 @@ class StringInputStream implements InputStream
      * Matches as far as possible until we reach a certain set of bytes
      * and returns the matched substring.
      *
-     * @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.
@@ -280,7 +279,7 @@ class StringInputStream implements InputStream
      * @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.
      *
      * @return string
      */
@@ -304,7 +303,7 @@ class StringInputStream implements InputStream
     /**
      * Unconsume characters.
      *
-     * @param int $howMany The number of characters to unconsume
+     * @param int $howMany The number of characters to unconsume.
      */
     public function unconsume($howMany = 1)
     {
diff --git a/src/HTML5/Parser/Tokenizer.php b/src/HTML5/Parser/Tokenizer.php
index cfd0e43..6284733 100644
--- a/src/HTML5/Parser/Tokenizer.php
+++ b/src/HTML5/Parser/Tokenizer.php
@@ -56,8 +56,8 @@ class Tokenizer
      * it a scanner (input) and an event handler (output), and then calling
      * the Tokenizer::parse() method.`
      *
-     * @param Scanner      $scanner      A scanner initialized with an input stream
-     * @param EventHandler $eventHandler An event handler, initialized and ready to receive events
+     * @param Scanner      $scanner      A scanner initialized with an input stream.
+     * @param EventHandler $eventHandler An event handler, initialized and ready to receive events.
      * @param string       $mode
      */
     public function __construct($scanner, $eventHandler, $mode = self::CONFORMANT_HTML)
@@ -100,7 +100,7 @@ class Tokenizer
      * Normally, setting is done by the event handler via a special return code on
      * startTag(), but it can also be set manually using this function.
      *
-     * @param int    $textmode One of Elements::TEXT_*
+     * @param int    $textmode One of Elements::TEXT_*.
      * @param string $untilTag The tag that should stop RAW or RCDATA mode. Normal mode does not
      *                         use this indicator.
      */
@@ -204,7 +204,7 @@ class Tokenizer
     /**
      * This buffers the current token as character data.
      *
-     * @param string $tok the current token
+     * @param string $tok The current token.
      *
      * @return bool
      */
@@ -229,7 +229,7 @@ class Tokenizer
     /**
      * Read text in RAW mode.
      *
-     * @param string $tok the current token
+     * @param string $tok The current token.
      *
      * @return bool
      */
@@ -250,7 +250,7 @@ class Tokenizer
     /**
      * Read text in RCDATA mode.
      *
-     * @param string $tok the current token
+     * @param string $tok The current token.
      *
      * @return bool
      */
@@ -334,8 +334,7 @@ class Tokenizer
     }
 
     /**
-     * Consume an end tag.
-     * 8.2.4.9.
+     * Consume an end tag. See section 8.2.4.9.
      */
     protected function endTag()
     {
@@ -376,8 +375,7 @@ class Tokenizer
     }
 
     /**
-     * Consume a tag name and body.
-     * 8.2.4.10.
+     * Consume a tag name and body. See section 8.2.4.10.
      */
     protected function tagName()
     {
@@ -519,8 +517,7 @@ class Tokenizer
     }
 
     /**
-     * Consume an attribute value.
-     * 8.2.4.37 and after.
+     * Consume an attribute value. See section 8.2.4.37 and after.
      *
      * @return string|null
      */
@@ -568,7 +565,7 @@ class Tokenizer
      *                      termination of an attribute's value. E.g. "\"'" will stop at either
      *                      ' or ".
      *
-     * @return string the attribute value
+     * @return string The attribute value.
      */
     protected function quotedAttributeValue($quote)
     {
@@ -626,8 +623,7 @@ class Tokenizer
      * &lt;!--&lt/+foo&gt;--&gt;
      *
      * @param string $leading Prepend any leading characters. This essentially
-     *                        negates the need to backtrack, but it's sort of
-     *                        a hack.
+     *                        negates the need to backtrack, but it's sort of a hack.
      *
      * @return bool
      */
@@ -652,7 +648,6 @@ class Tokenizer
 
     /**
      * Read a comment.
-     *
      * Expects the first tok to be inside of the comment.
      *
      * @return bool
@@ -848,7 +843,7 @@ class Tokenizer
      * @param string $stopchars Characters (in addition to a close-quote) that should stop the string.
      *                          E.g. sometimes '>' is higher precedence than '"' or "'".
      *
-     * @return mixed String if one is found (quotations omitted)
+     * @return mixed String if one is found (quotations omitted).
      */
     protected function quotedString($stopchars)
     {
diff --git a/src/HTML5/Parser/TreeBuildingRules.php b/src/HTML5/Parser/TreeBuildingRules.php
index 9b94185..00d3951 100644
--- a/src/HTML5/Parser/TreeBuildingRules.php
+++ b/src/HTML5/Parser/TreeBuildingRules.php
@@ -45,7 +45,7 @@ class TreeBuildingRules
      *
      * This may modify the existing DOM.
      *
-     * @return \DOMElement the new Current DOM element
+     * @return \DOMElement The new Current DOM element.
      */
     public function evaluate($new, $current)
     {
diff --git a/src/HTML5/Parser/UTF8Utils.php b/src/HTML5/Parser/UTF8Utils.php
index 77c2dfb..bbf6d5b 100644
--- a/src/HTML5/Parser/UTF8Utils.php
+++ b/src/HTML5/Parser/UTF8Utils.php
@@ -131,9 +131,9 @@ class UTF8Utils
     /**
      * Checks for Unicode code points that are not valid in a document.
      *
-     * @param string $data a string to analyze
+     * @param string $data A string to analyze
      *
-     * @return array an array of (string) error messages produced by the scanning
+     * @return array An array of (string) error messages produced by the scanning
      */
     public static function checkForIllegalCodepoints($data)
     {