Normalize PHPDoc comments

18 files changed, 118 insertions, 134 deletions

diff --git a/.php_cs.dist b/.php_cs.dist
index 857e9f0..d5e4918 100644
--- a/.php_cs.dist
+++ b/.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)
 ;
diff --git a/.travis.yml b/.travis.yml
index 3e31ef1..f10bcf3 100644
--- a/.travis.yml
+++ b/.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
 
diff --git a/src/HTML5.php b/src/HTML5.php
index 168b965..3d7eee9 100644
--- a/src/HTML5.php
+++ b/src/HTML5.php
@@ -57,7 +57,7 @@ class HTML5
      * @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 @@ class HTML5
      * 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 @@ class HTML5
      * @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 @@ class HTML5
      * 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 @@ class HTML5
     /**
      * 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 @@ class HTML5
     /**
      * 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())
     {
diff --git a/src/HTML5/Elements.php b/src/HTML5/Elements.php
index a139e26..8fe7987 100644
--- a/src/HTML5/Elements.php
+++ b/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 @@ class Elements
     /**
      * 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 @@ class Elements
     /**
      * 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 @@ class Elements
     /**
      * 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 @@ class Elements
 
     /**
      * 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 @@ class Elements
     /**
      * 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 @@ class Elements
     /**
      * 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 @@ class Elements
     /**
      * 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 @@ class Elements
 
     /**
      * 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)
     {
diff --git a/src/HTML5/InstructionProcessor.php b/src/HTML5/InstructionProcessor.php
index 3a88a10..33a73fc 100644
--- a/src/HTML5/InstructionProcessor.php
+++ b/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,
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)
     {
diff --git a/src/HTML5/Serializer/OutputRules.php b/src/HTML5/Serializer/OutputRules.php
index 2711d1b..41616d5 100644
--- a/src/HTML5/Serializer/OutputRules.php
+++ b/src/HTML5/Serializer/OutputRules.php
@@ -251,7 +251,7 @@ class OutputRules implements RulesInterface
     /**
      * Write a text node.
      *
-     * @param \DOMText $ele The text node to write
+     * @param \DOMText $ele The text node to write.
      */
     public function text($ele)
     {
@@ -290,8 +290,7 @@ class OutputRules implements RulesInterface
     /**
      * Write the namespace attributes.
      *
-     *
-     * @param \DOMNode $ele The element being written
+     * @param \DOMNode $ele The element being written.
      */
     protected function namespaceAttrs($ele)
     {
@@ -312,7 +311,7 @@ class OutputRules implements RulesInterface
      * Tags for HTML, MathML, and SVG are in the local name. Otherwise, use the
      * qualified name (8.3).
      *
-     * @param \DOMNode $ele The element being written
+     * @param \DOMNode $ele The element being written.
      */
     protected function openTag($ele)
     {
@@ -426,7 +425,7 @@ class OutputRules implements RulesInterface
      * Tags for HTML, MathML, and SVG are in the local name. Otherwise, use the
      * qualified name (8.3).
      *
-     * @param \DOMNode $ele The element being written
+     * @param \DOMNode $ele The element being written.
      */
     protected function closeTag($ele)
     {
@@ -440,7 +439,7 @@ class OutputRules implements RulesInterface
      *
      * @param string $text The string to put into the output
      *
-     * @return Traverser $this so it can be used in chaining
+     * @return $this
      */
     protected function wr($text)
     {
@@ -452,7 +451,7 @@ class OutputRules implements RulesInterface
     /**
      * Write a new line character.
      *
-     * @return Traverser $this so it can be used in chaining
+     * @return $this
      */
     protected function nl()
     {
@@ -483,10 +482,10 @@ class OutputRules implements RulesInterface
      *
      * @todo Use the Entities class in php 5.3 to have html5 entities.
      *
-     * @param string $text      text to encode
-     * @param bool   $attribute True if we are encoding an attrubute, false otherwise
+     * @param string $text      Text to encode.
+     * @param bool   $attribute True if we are encoding an attrubute, false otherwise.
      *
-     * @return string the encoded text
+     * @return string The encoded text.
      */
     protected function enc($text, $attribute = false)
     {
@@ -521,8 +520,8 @@ class OutputRules implements RulesInterface
      *
      * @see http://www.w3.org/TR/2013/CR-html5-20130806/syntax.html#escapingString
      *
-     * @param string $text      text to escape
-     * @param bool   $attribute True if we are escaping an attrubute, false otherwise
+     * @param string $text      Text to escape.
+     * @param bool   $attribute True if we are escaping an attrubute, false otherwise.
      */
     protected function escape($text, $attribute = false)
     {
diff --git a/src/HTML5/Serializer/RulesInterface.php b/src/HTML5/Serializer/RulesInterface.php
index 6d3f60e..69a6ecd 100644
--- a/src/HTML5/Serializer/RulesInterface.php
+++ b/src/HTML5/Serializer/RulesInterface.php
@@ -19,8 +19,8 @@ interface RulesInterface
      *
      * Note, before the rules can be used a traverser must be registered.
      *
-     * @param mixed $output  The output stream to write output to
-     * @param array $options An array of options
+     * @param mixed $output  The output stream to write output to.
+     * @param array $options An array of options.
      */
     public function __construct($output, $options = array());
 
@@ -29,9 +29,9 @@ interface RulesInterface
      *
      * Note, only one traverser can be used by the rules.
      *
-     * @param Traverser $traverser The traverser used in the rules
+     * @param Traverser $traverser The traverser used in the rules.
      *
-     * @return RulesInterface $this for the current object
+     * @return RulesInterface $this for the current object.
      */
     public function setTraverser(Traverser $traverser);
 
diff --git a/src/HTML5/Serializer/Traverser.php b/src/HTML5/Serializer/Traverser.php
index a33943f..1e8d792 100644
--- a/src/HTML5/Serializer/Traverser.php
+++ b/src/HTML5/Serializer/Traverser.php
@@ -35,7 +35,7 @@ class Traverser
     /**
      * Create a traverser.
      *
-     * @param \DOMNode|\DOMNodeList $dom     The document or node to traverse
+     * @param \DOMNode|\DOMNodeList $dom     The document or node to traverse.
      * @param resource              $out     A stream that allows writing. The traverser will output into this
      *                                       stream.
      * @param array                 $options An array of options for the traverser as key/value pairs. These include:
@@ -56,7 +56,7 @@ class Traverser
     /**
      * Tell the traverser to walk the DOM.
      *
-     * @return resource $out Returns the output stream
+     * @return resource $out Returns the output stream.
      */
     public function walk()
     {
@@ -83,7 +83,7 @@ class Traverser
     /**
      * Process a node in the DOM.
      *
-     * @param mixed $node A node implementing \DOMNode
+     * @param mixed $node A node implementing \DOMNode.
      */
     public function node($node)
     {
@@ -114,7 +114,7 @@ class Traverser
     /**
      * Walk through all the nodes on a node list.
      *
-     * @param \DOMNodeList $nl A list of child elements to walk through
+     * @param \DOMNodeList $nl A list of child elements to walk through.
      */
     public function children($nl)
     {
@@ -126,9 +126,9 @@ class Traverser
     /**
      * Is an element local?
      *
-     * @param mixed $ele An element that implement \DOMNode
+     * @param mixed $ele An element that implement \DOMNode.
      *
-     * @return bool true if local and false otherwise
+     * @return bool true if local and false otherwise.
      */
     public function isLocalElement($ele)
     {