[CssSelector] Added PHPDoc blocks to first-level classes.

src/Symfony/Component/CssSelector/Parser.php

@@ -25,7 +25,16 @@ namespace Symfony\Component\CssSelector;
 class Parser
 {
     /**
+     * Translate a CSS expression to its XPath equivalent.
+     * Optionally, a prefix can be added to the resulting XPath
+     * expression with the $prefix parameter.
+     *
      * @throws SyntaxError When got None for xpath expression
+     *
+     * @param  mixed  $cssExpr The CSS expression.
+     * @param  string $prefix  An optional prefix for the XPath expression.
+     *
+     * @return string
      */
     static public function cssToXpath($cssExpr, $prefix = 'descendant-or-self::')
     {
@@ -62,7 +71,14 @@ class Parser
     }
 
     /**
+     * Parse an expression and return the Node object that represents
+     * the parsed expression.
+     *
      * @throws \Exception When tokenizer throws it while parsing
+     *
+     * @param  string $string The expression to parse
+     *
+     * @return Node\NodeInterface
      */
     public function parse($string)
     {
@@ -79,6 +95,14 @@ class Parser
         }
     }
 
+    /**
+     * Parse a selector group contained in $stream and return
+     * the Node object that represents the expression.
+     *
+     * @param  TokenStream $stream The stream to parse.
+     *
+     * @return Node\NodeInterface
+     */
     protected function parseSelectorGroup($stream)
     {
         $result = array();
@@ -99,7 +123,14 @@ class Parser
     }
 
     /**
+     * Parse a selector contained in $stream and return the Node
+     * object that represents it.
+     *
      * @throws SyntaxError When expected selector but got something else
+     *
+     * @param  TokenStrem $stream The stream containing the selector.
+     *
+     * @return Node\NodeInterface
      */
     protected function parseSelector($stream)
     {
@@ -128,7 +159,14 @@ class Parser
     }
 
     /**
+     * Parse a simple selector (the current token) from $stream and return
+     * the resulting Node object.
+     *
      * @throws SyntaxError When expected symbol but got something else
+     *
+     * @param  TokenStream The stream containing the selector.
+     *
+     * @return Node\NodeInterface
      */
     protected function parseSimpleSelector($stream)
     {
@@ -228,7 +266,16 @@ class Parser
     }
 
     /**
+     * Parse an attribute from a selector contained in $stream and return
+     * the resulting AttribNode object.
+     *
      * @throws SyntaxError When encountered unexpected selector
+     *
+     * @param  Node\NodeInterface $selector The selector object whose attribute
+     *                                      is to be parsed.
+     * @param  TokenStream        $strem    The container token stream.
+     *
+     * @return Node\AttribNode
      */
     protected function parseAttrib($selector, $stream)
     {

src/Symfony/Component/CssSelector/Token.php

@@ -25,6 +25,13 @@ class Token
     protected $value;
     protected $position;
 
+    /**
+     * Constructor.
+     *
+     * @param string $type     The type of this token.
+     * @param mixed  $value    The value of this token.
+     * @param int    $position The order of this token.
+     */
     public function __construct($type, $value, $position)
     {
         $this->type = $type;
@@ -32,16 +39,33 @@ class Token
         $this->position = $position;
     }
 
+    /**
+     * Get a string representation of this token.
+     *
+     * @return string
+     */
     public function __toString()
     {
         return (string) $this->value;
     }
 
+    /**
+     * Answer whether this token's type equals to $type.
+     *
+     * @param  string $type The type to test against this token's one.
+     *
+     * @return bool
+     */
     public function isType($type)
     {
         return $this->type == $type;
     }
 
+    /**
+     * Get the position of this token.
+     *
+     * @return int
+     */
     public function getPosition()
     {
         return $this->position;

src/Symfony/Component/CssSelector/TokenStream.php

@@ -27,6 +27,12 @@ class TokenStream
     protected $peeked;
     protected $peeking;
 
+    /**
+     * Constructor.
+     *
+     * @param array $tokens The tokens that make the stream.
+     * @param mixed $source The source of the stream.
+     */
     public function __construct($tokens, $source = null)
     {
         $this->used = array();
@@ -36,11 +42,23 @@ class TokenStream
         $this->peeking = false;
     }
 
+    /**
+     * Get the tokens that have already been visited in this stream.
+     *
+     * @return array
+     */
     public function getUsed()
     {
         return $this->used;
     }
 
+    /**
+     * Get the next token in the stream or null if there is none.
+     * Note that if this stream was set to be peeking its behavior
+     * will be restored to not peeking after this operation.
+     *
+     * @return mixed
+     */
     public function next()
     {
         if ($this->peeking) {
@@ -60,6 +78,16 @@ class TokenStream
         return $next;
     }
 
+    /**
+     * Peek for the next token in this stream. This means that the next token
+     * will be returned but it won't be considered as used (visited) until the
+     * next() method is invoked.
+     * If there are no remaining tokens null will be returned.
+     *
+     * @see next()
+     *
+     * @return mixed
+     */
     public function peek()
     {
         if (!$this->peeking) {

src/Symfony/Component/CssSelector/Tokenizer.php

@@ -21,6 +21,14 @@ namespace Symfony\Component\CssSelector;
  */
 class Tokenizer
 {
+    /**
+     * Take a CSS selector and return an array holding the Tokens
+     * it contains.
+     *
+     * @param  string $s The selector to lex.
+     *
+     * @return array Token[]
+     */
     public function tokenize($s)
     {
         if (function_exists('mb_internal_encoding') && ((int) ini_get('mbstring.func_overload')) & 2) {
@@ -95,7 +103,16 @@ class Tokenizer
     }
 
     /**
+     * Tokenize a quoted string (i.e. 'A string quoted with \' characters'),
+     * and return an array holding the unquoted string contained by $s and
+     * the new position from which tokenizing should take over.
+     *
      * @throws SyntaxError When expected closing is not found
+     *
+     * @param  string $s   The selector string containing the quoted string.
+     * @param  int    $pos The starting position for the quoted string.
+     *
+     * @return array
      */
     protected function tokenizeEscapedString($s, $pos)
     {
@@ -125,7 +142,13 @@ class Tokenizer
     }
 
     /**
+     * Unescape a string literal and return the unescaped string.
+     *
      * @throws SyntaxError When invalid escape sequence is found
+     *
+     * @param  string $literal The string literal to unescape.
+     *
+     * @return string
      */
     protected function unescapeStringLiteral($literal)
     {
@@ -143,7 +166,16 @@ class Tokenizer
     }
 
     /**
+     * Lex selector $s and return the an array holding the name of the symbol
+     * contained in it and the new position from which tokenizing should take
+     * over.
+     *
      * @throws SyntaxError When Unexpected symbol is found
+     *
+     * @param  string $s   The selector string.
+     * @param  int    $pos The position in $s at which the symbol starts.
+     *
+     * @return array
      */
     protected function tokenizeSymbol($s, $pos)
     {

src/Symfony/Component/CssSelector/XPathExpr.php

@@ -27,6 +27,15 @@ class XPathExpr
     protected $condition;
     protected $starPrefix;
 
+    /**
+     * Constructor.
+     *
+     * @param string $prefix     Prefix for the XPath expression.
+     * @param string $path       Actual path of the expression.
+     * @param string $element    The element in the expression.
+     * @param string $condition  A condition for the expression.
+     * @param bool   $starPrefix Indicates whether to use a star prefix.
+     */
     public function __construct($prefix = null, $path = null, $element = '*', $condition = null, $starPrefix = false)
     {
         $this->prefix = $prefix;
@@ -36,31 +45,61 @@ class XPathExpr
         $this->starPrefix = $starPrefix;
     }
 
+    /**
+     * Get the prefix of this XPath expression.
+     *
+     * @return string
+     */
     public function getPrefix()
     {
         return $this->prefix;
     }
 
+    /**
+     * Get the path of this XPath expression.
+     *
+     * @return string
+     */
     public function getPath()
     {
         return $this->path;
     }
 
+    /**
+     * Answer whether this XPath expression has a star prefix.
+     *
+     * @return bool
+     */
     public function hasStarPrefix()
     {
         return $this->starPrefix;
     }
 
+    /**
+     * Get the element of this XPath expression.
+     *
+     * @return string
+     */
     public function getElement()
     {
         return $this->element;
     }
 
+    /**
+     * Get the condition of this XPath expression.
+     *
+     * @return string
+     */
     public function getCondition()
     {
         return $this->condition;
     }
 
+    /**
+     * Get a string representation for this XPath expression.
+     *
+     * @return string
+     */
     public function __toString()
     {
         $path = '';
@@ -81,6 +120,12 @@ class XPathExpr
         return $path;
     }
 
+    /**
+     * Add a condition to this XPath expression.
+     * Any pre-existant condition will be ANDed to it.
+     *
+     * @param string $condition The condition to add.
+     */
     public function addCondition($condition)
     {
         if ($this->condition) {
@@ -90,6 +135,12 @@ class XPathExpr
         }
     }
 
+    /**
+     * Add a prefix to this XPath expression.
+     * It will be prepended to any pre-existant prefixes.
+     *
+     * @param string $prefix  The prefix to add.
+     */
     public function addPrefix($prefix)
     {
         if ($this->prefix) {
@@ -99,6 +150,11 @@ class XPathExpr
         }
     }
 
+    /**
+     * Add a condition to this XPath expression using the name of the element
+     * as the desired value.
+     * This method resets the element to '*'.
+     */
     public function addNameTest()
     {
         if ($this->element == '*') {
@@ -110,6 +166,11 @@ class XPathExpr
         $this->element = '*';
     }
 
+    /**
+     * Add a star prefix to this XPath expression.
+     * This method will prepend a '*' to the path and set the star prefix flag
+     * to true.
+     */
     public function addStarPrefix()
     {
         /*
@@ -125,6 +186,14 @@ class XPathExpr
         $this->starPrefix = true;
     }
 
+    /**
+     * Join this XPath expression with $other (another XPath expression) using
+     * $combiner to join them.
+     *
+     * @param string    $combiner The combiner string.
+     * @param XPathExpr $other    The other XPath expression to combine with
+     *                            this one.
+     */
     public function join($combiner, $other)
     {
         $prefix = (string) $this;
@@ -143,6 +212,13 @@ class XPathExpr
         $this->condition = $other->GetCondition();
     }
 
+    /**
+     * Get an XPath literal for $s.
+     *
+     * @param  mixed $s Can either be a Node\ElementNode or a string.
+     *
+     * @return string
+     */
     static public function xpathLiteral($s)
     {
         if ($s instanceof Node\ElementNode) {

src/Symfony/Component/CssSelector/XPathExprOr.php

@@ -23,12 +23,23 @@ namespace Symfony\Component\CssSelector;
  */
 class XPathExprOr extends XPathExpr
 {
+    /**
+     * Constructor.
+     *
+     * @param array  $items  The items in the expression.
+     * @param string $prefix Optional prefix for the expression.
+     */
     public function __construct($items, $prefix = null)
     {
         $this->items = $items;
         $this->prefix = $prefix;
     }
 
+    /**
+     * Get a string representation of this |'d expression.
+     *
+     * @return string
+     */
     public function __toString()
     {
         $prefix = $this->prefix;