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

symfony · jmikola · Feb 5, 2011 · Jan 24, 2011 · Feb 5, 2011 · Feb 2, 2011
commit 562ebd56082a93c70f0ba81a68f3cca020d3521a
diff --git a/src/Symfony/Component/CssSelector/Parser.php b/src/Symfony/Component/CssSelector/Parser.php
@@ -25,7 +25,16 @@
 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 @@ static public function cssToXpath($cssExpr, $prefix = 'descendant-or-self::')
     }
 
     /**
+     * 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 @@ public function parse($string)
         }
     }
 
+    /**
+     * 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 @@ protected function parseSelectorGroup($stream)
     }
 
     /**
+     * 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 @@ protected function parseSelector($stream)
     }
 
     /**
+     * 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 @@ protected function parseSimpleSelector($stream)
     }
 
     /**
+     * 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)
     {

diff --git a/src/Symfony/Component/CssSelector/Token.php b/src/Symfony/Component/CssSelector/Token.php
@@ -25,23 +25,47 @@ 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;
         $this->value = $value;
         $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;

diff --git a/src/Symfony/Component/CssSelector/TokenStream.php b/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 @@ public function __construct($tokens, $source = null)
         $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 @@ public function next()
         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) {

diff --git a/src/Symfony/Component/CssSelector/Tokenizer.php b/src/Symfony/Component/CssSelector/Tokenizer.php
@@ -21,6 +21,14 @@
  */
 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 @@ public function tokenize($s)
     }
 
     /**
+     * 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 @@ protected function tokenizeEscapedString($s, $pos)
     }
 
     /**
+     * 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 @@ protected function unescapeStringLiteral($literal)
     }
 
     /**
+     * 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.

5432
+     *
+     * @return array
      */
     protected function tokenizeSymbol($s, $pos)
     {