[CssSelector] PHPDoc additions

src/Symfony/Component/CssSelector/Node/AttribNode.php

@@ -30,6 +30,15 @@ class AttribNode implements NodeInterface
     protected $operator;
     protected $value;
 
+    /**
+     * Constructor.
+     *
+     * @param NodeInterface $selector The XPath selector
+     * @param string $namespace The namespace
+     * @param string $attrib The attribute
+     * @param string $operator The operator
+     * @param string $value The value
+     */
     public function __construct($selector, $namespace, $attrib, $operator, $value)
     {
         $this->selector = $selector;
@@ -39,6 +48,9 @@ class AttribNode implements NodeInterface
         $this->value = $value;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function __toString()
     {
         if ($this->operator == 'exists') {
@@ -49,7 +61,7 @@ class AttribNode implements NodeInterface
     }
 
     /**
-     * @throws SyntaxError When unknown operator is found
+     * {@inheritDoc}
      */
     public function toXpath()
     {
@@ -88,6 +100,11 @@ class AttribNode implements NodeInterface
         return $path;
     }
 
+    /**
+     * Returns the XPath Attribute
+     *
+     * @return string The XPath attribute
+     */
     protected function xpathAttrib()
     {
         // FIXME: if attrib is *?
@@ -98,6 +115,11 @@ class AttribNode implements NodeInterface
         return sprintf('@%s:%s', $this->namespace, $this->attrib);
     }
 
+    /**
+     * Returns a formatted attribute
+     *
+     * @return string The formatted attributep
+     */
     protected function formatAttrib()
     {
         if ($this->namespace == '*') {

src/Symfony/Component/CssSelector/Node/ClassNode.php

@@ -26,17 +26,29 @@ class ClassNode implements NodeInterface
     protected $selector;
     protected $className;
 
+    /**
+     * The constructor.
+     *
+     * @param NodeInterface $selector The XPath Selector
+     * @param string $className The class name
+     */
     public function __construct($selector, $className)
     {
         $this->selector = $selector;
         $this->className = $className;
     }
 
+    /**
+     * {@inheritDoc} 
+     */
     public function __toString()
     {
         return sprintf('%s[%s.%s]', __CLASS__, $this->selector, $this->className);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function toXpath()
     {
         $selXpath = $this->selector->toXpath();

src/Symfony/Component/CssSelector/Node/CombinedSelectorNode.php

@@ -34,6 +34,13 @@ class CombinedSelectorNode implements NodeInterface
     protected $combinator;
     protected $subselector;
 
+    /**
+     * The constructor.
+     *
+     * @param NodeInterface $selector The XPath selector
+     * @param string $combinator The combinator
+     * @param NodeInterface $subselector The sub XPath selector
+     */
     public function __construct($selector, $combinator, $subselector)
     {
         $this->selector = $selector;
@@ -41,6 +48,9 @@ class CombinedSelectorNode implements NodeInterface
         $this->subselector = $subselector;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function __toString()
     {
         $comb = $this->combinator == ' ' ? '<followed>' : $this->combinator;
@@ -49,6 +59,7 @@ class CombinedSelectorNode implements NodeInterface
     }
 
     /**
+     * {@inheritDoc}
      * @throws SyntaxError When unknown combinator is found
      */
     public function toXpath()
@@ -63,6 +74,12 @@ class CombinedSelectorNode implements NodeInterface
         return $this->$method($path, $this->subselector);
     }
 
+    /**
+     * Joins a NodeInterface into the XPath of this object.
+     *
+     * @param XPathExpr $xpath The XPath expression for this object
+     * @param NodeInterface $sub The NodeInterface object to add
+     */
     protected function _xpath_descendant($xpath, $sub)
     {
         // when sub is a descendant in any way of xpath
@@ -71,6 +88,12 @@ class CombinedSelectorNode implements NodeInterface
         return $xpath;
     }
 
+    /**
+     * Joins a NodeInterface as a child of this object.
+     *
+     * @param XPathExpr $xpath The parent XPath expression
+     * @param NodeInterface $sub The NodeInterface object to add
+     */
     protected function _xpath_child($xpath, $sub)
     {
         // when sub is an immediate child of xpath
@@ -79,6 +102,12 @@ class CombinedSelectorNode implements NodeInterface
         return $xpath;
     }
 
+    /**
+     * Joins an XPath expression as an adjacent of another.
+     *
+     * @param XPathExpr $xpath The parent XPath expression
+     * @param NodeInterface $sub The adjacent XPath expression
+     */
     protected function _xpath_direct_adjacent($xpath, $sub)
     {
         // when sub immediately follows xpath
@@ -89,6 +118,12 @@ class CombinedSelectorNode implements NodeInterface
         return $xpath;
     }
 
+    /**
+     * Joins an XPath expression as an indirect adjacent of another.
+     *
+     * @param XPathExpr $xpath The parent XPath expression
+     * @param NodeInterface $sub The indirect adjacent NodeInterface object
+     */
     protected function _xpath_indirect_adjacent($xpath, $sub)
     {
         // when sub comes somewhere after xpath as a sibling

src/Symfony/Component/CssSelector/Node/ElementNode.php

@@ -26,17 +26,31 @@ class ElementNode implements NodeInterface
     protected $namespace;
     protected $element;
 
+    /**
+     * Constructor.
+     *
+     * @param string $namespace Namespace
+     * @param string $element Element
+     */ 
     public function __construct($namespace, $element)
     {
         $this->namespace = $namespace;
         $this->element = $element;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function __toString()
     {
         return sprintf('%s[%s]', __CLASS__, $this->formatElement());
     }
 
+    /**
+     * Formats the element into a string.
+     *
+     * @return string Element as an XPath string
+     */
     public function formatElement()
     {
         if ($this->namespace == '*') {
@@ -46,6 +60,9 @@ class ElementNode implements NodeInterface
         return sprintf('%s|%s', $this->namespace, $this->element);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function toXpath()
     {
         if ($this->namespace == '*') {

src/Symfony/Component/CssSelector/Node/FunctionNode.php

@@ -31,6 +31,14 @@ class FunctionNode implements NodeInterface
     protected $name;
     protected $expr;
 
+    /**
+     * Constructor.
+     *
+     * @param NodeInterface $selector The XPath expression
+     * @param string $type
+     * @param string $name
+     * @param XPathExpr $expr 
+     */
     public function __construct($selector, $type, $name, $expr)
     {
         $this->selector = $selector;
@@ -39,12 +47,16 @@ class FunctionNode implements NodeInterface
         $this->expr = $expr;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function __toString()
     {
         return sprintf('%s[%s%s%s(%s)]', __CLASS__, $this->selector, $this->type, $this->name, $this->expr);
     }
 
     /**
+     * {@inheritDoc}
      * @throws SyntaxError When unsupported or unknown pseudo-class is found
      */
     public function toXpath()
@@ -61,6 +73,15 @@ class FunctionNode implements NodeInterface
         return $this->$method($sel_path, $this->expr);
     }
 
+    /**
+     * undocumented function
+     *
+     * @param XPathExpr $xpath 
+     * @param mixed $expr 
+     * @param string $last 
+     * @param string $addNameTest 
+     * @return XPathExpr
+     */
     protected function _xpath_nth_child($xpath, $expr, $last = false, $addNameTest = true)
     {
         list($a, $b) = $this->parseSeries($expr);
@@ -124,11 +145,25 @@ class FunctionNode implements NodeInterface
              -1n+6 means elements 6 and previous */
     }
 
+    /**
+     * undocumented function
+     *
+     * @param XPathExpr $xpath 
+     * @param XPathExpr $expr 
+     * @return XPathExpr
+     */
     protected function _xpath_nth_last_child($xpath, $expr)
     {
         return $this->_xpath_nth_child($xpath, $expr, true);
     }
 
+    /**
+     * undocumented function
+     *
+     * @param XPathExpr $xpath 
+     * @param XPathExpr $expr 
+     * @return XPathExpr
+     */
     protected function _xpath_nth_of_type($xpath, $expr)
     {
         if ($xpath->getElement() == '*') {
@@ -138,11 +173,25 @@ class FunctionNode implements NodeInterface
         return $this->_xpath_nth_child($xpath, $expr, false, false);
     }
 
+    /**
+     * undocumented function
+     *
+     * @param XPathExpr $xpath 
+     * @param XPathExpr $expr 
+     * @return XPathExpr
+     */
     protected function _xpath_nth_last_of_type($xpath, $expr)
     {
         return $this->_xpath_nth_child($xpath, $expr, true, false);
     }
 
+    /**
+     * undocumented function
+     *
+     * @param XPathExpr $xpath 
+     * @param XPathExpr $expr 
+     * @return XPathExpr
+     */
     protected function _xpath_contains($xpath, $expr)
     {
         // text content, minus tags, must contain expr
@@ -159,6 +208,13 @@ class FunctionNode implements NodeInterface
         return $xpath;
     }
 
+    /**
+     * undocumented function
+     *
+     * @param XPathExpr $xpath 
+     * @param XPathExpr $expr 
+     * @return XPathExpr
+     */
     protected function _xpath_not($xpath, $expr)
     {
         // everything for which not expr applies
@@ -170,7 +226,12 @@ class FunctionNode implements NodeInterface
         return $xpath;
     }
 
-    // Parses things like '1n+2', or 'an+b' generally, returning (a, b)
+    /**
+     * Parses things like '1n+2', or 'an+b' generally, returning (a, b)
+     *
+     * @param mixed $s 
+     * @return array
+     */
     protected function parseSeries($s)
     {
         if ($s instanceof ElementNode) {

src/Symfony/Component/CssSelector/Node/HashNode.php

@@ -26,17 +26,29 @@ class HashNode implements NodeInterface
     protected $selector;
     protected $id;
 
+    /**
+     * Constructor.
+     *
+     * @param NodeInterface $selector The NodeInterface object
+     * @param string $id The ID
+     */
     public function __construct($selector, $id)
     {
         $this->selector = $selector;
         $this->id = $id;
     }
 
+    /** 
+     * {@inheritDoc}
+     */
     public function __toString()
     {
         return sprintf('%s[%s#%s]', __CLASS__, $this->selector, $this->id);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function toXpath()
     {
         $path = $this->selector->toXpath();

src/Symfony/Component/CssSelector/Node/NodeInterface.php

@@ -21,7 +21,17 @@ namespace Symfony\Component\CssSelector\Node;
  */
 interface NodeInterface
 {
+    /**
+     * Returns a string representation of the object.
+     *
+     * @return string The string representation
+     */
     function __toString();
 
+    /**
+     * @return XPathExpr The XPath expression
+     *
+     * @throws SyntaxError When unknown operator is found
+     */
     function toXpath();
 }

src/Symfony/Component/CssSelector/Node/OrNode.php

@@ -25,16 +25,27 @@ class OrNode implements NodeInterface
 {
     protected $items;
 
+    /**
+     * Constructor.
+     *
+     * @param array $items An array of NodeInterface objects
+     */
     public function __construct($items)
     {
         $this->items = $items;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function __toString()
     {
         return sprintf('%s(%s)', __CLASS__, $this->items);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function toXpath()
     {
         $paths = array();

src/Symfony/Component/CssSelector/Node/PseudoNode.php

@@ -34,6 +34,11 @@ class PseudoNode implements NodeInterface
     protected $ident;
 
     /**
+     * Constructor.
+     *
+     * @param NodeInterface $element The NodeInterface element
+     * @param string $type Node type
+     * @param string $ident The ident
      * @throws SyntaxError When incorrect PseudoNode type is given
      */
     public function __construct($element, $type, $ident)
@@ -48,12 +53,16 @@ class PseudoNode implements NodeInterface
         $this->ident = $ident;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function __toString()
     {
         return sprintf('%s[%s%s%s]', __CLASS__, $this->element, $this->type, $this->ident);
     }
 
     /**
+     * {@inheritDoc}
      * @throws SyntaxError When unsupported or unknown pseudo-class is found
      */
     public function toXpath()
@@ -71,6 +80,11 @@ class PseudoNode implements NodeInterface
         return $this->$method($el_xpath);
     }
 
+    /**
+     *
+     * @param XPathExpr $xpath The XPath expression
+     * @return XPathExpr The modified XPath expression
+     */
     protected function xpath_checked($xpath)
     {
         // FIXME: is this really all the elements?
@@ -80,6 +94,8 @@ class PseudoNode implements NodeInterface
     }
 
     /**
+     * @param XPathExpr $xpath The XPath expression
+     * @return XPathExpr The modified XPath expression
      * @throws SyntaxError If this element is the root element
      */
     protected function xpath_root($xpath)
@@ -88,6 +104,12 @@ class PseudoNode implements NodeInterface
         throw new SyntaxError();
     }
 
+    /**
+     * Marks this XPath expression as the first child.
+     *
+     * @param XPathExpr $xpath The XPath expression
+     * @return XPathExpr The modified expression
+     */
     protected function xpath_first_child($xpath)
     {
         $xpath->addStarPrefix();
@@ -97,6 +119,12 @@ class PseudoNode implements NodeInterface
         return $xpath;
     }
 
+    /** 
+     * Sets the XPath  to be the last child.
+     *
+     * @param XPathExpr $xpath The XPath expression
+     * @return XPathExpr The modified expression
+     */
     protected function xpath_last_child($xpath)
     {
         $xpath->addStarPrefix();
@@ -106,6 +134,12 @@ class PseudoNode implements NodeInterface
         return $xpath;
     }
 
+    /**
+     * Sets the XPath expression to be the first of type.
+     *
+     * @param XPathExpr $xpath The XPath expression
+     * @return XPathExpr The modified expression
+     */
     protected function xpath_first_of_type($xpath)
     {
         if ($xpath->getElement() == '*') {
@@ -118,6 +152,10 @@ class PseudoNode implements NodeInterface
     }
 
     /**
+     * Sets the XPath expression to be the last of type.
+     *
+     * @param XPathExpr $xpath The XPath expression
+     * @return XPathExpr The modified expression
      * @throws SyntaxError Because *:last-of-type is not implemented
      */
     protected function xpath_last_of_type($xpath)
@@ -131,6 +169,12 @@ class PseudoNode implements NodeInterface
         return $xpath;
     }
 
+    /**
+     * Sets the XPath expression to be the only child.
+     *
+     * @param XPathExpr $xpath The XPath expression
+     * @return XPathExpr The modified expression
+     */
     protected function xpath_only_child($xpath)
     {
         $xpath->addNameTest();
@@ -141,6 +185,10 @@ class PseudoNode implements NodeInterface
     }
 
     /**
+     * Sets the XPath expression to be only of type.
+     *
+     * @param XPathExpr $xpath The XPath expression
+     * @return XPathExpr The modified expression
      * @throws SyntaxError Because *:only-of-type is not implemented
      */
     protected function xpath_only_of_type($xpath)
@@ -153,6 +201,12 @@ class PseudoNode implements NodeInterface
         return $xpath;
     }
 
+    /**
+     * undocumented function
+     *
+     * @param XPathExpr $xpath The XPath expression
+     * @return XPathExpr The modified expression
+     */
     protected function xpath_empty($xpath)
     {
         $xpath->addCondition('not(*) and not(normalize-space())');