merged branch stloyd/crawler_phpdoc (PR #3834)

Commits
-------

292364a [DomCrawler] Added some docbocks into DomCrawler classes. Closes #3832

Discussion
----------

[DomCrawler] Added some docbocks into DomCrawler classes, reordered func...

...tions to follow Symfony 2 CS. Closes #3832

---------------------------------------------------------------------------

by fabpot at 2012-04-08T10:38:39Z

Can you revert the code move as it makes merges between 2.0 and master much more complex. Thanks.

---------------------------------------------------------------------------

by stloyd at 2012-04-08T11:36:53Z

Reverted and changed commit message.

@fabpot Should I make PR for `master` according to CS ?

---------------------------------------------------------------------------

by stof at 2012-04-08T11:40:58Z

@stloyd this can be considered as a bugfix as you are fixing the phpdoc. So 2.0 is fine

src/Symfony/Component/DomCrawler/Crawler.php

@@ -22,6 +22,9 @@ use Symfony\Component\CssSelector\CssSelector;
  */
 class Crawler extends \SplObjectStorage
 {
+    /**
+     * @var string The current URI or the base href value
+     */
     private $uri;
 
     /**
@@ -75,8 +78,10 @@ class Crawler extends \SplObjectStorage
     /**
      * Adds HTML/XML content.
      *
-     * @param string $content A string to parse as HTML/XML
-     * @param string $type    The content type of the string
+     * @param string      $content A string to parse as HTML/XML
+     * @param null|string $type    The content type of the string
+     *
+     * @return null|void
      */
     public function addContent($content, $type = null)
     {
@@ -208,7 +213,7 @@ class Crawler extends \SplObjectStorage
      *
      * @param integer $position The position
      *
-     * @return A new instance of the Crawler with the selected node, or an empty Crawler if it does not exist.
+     * @return Crawler A new instance of the Crawler with the selected node, or an empty Crawler if it does not exist.
      *
      * @api
      */

src/Symfony/Component/DomCrawler/Field/ChoiceFormField.php

@@ -22,8 +22,17 @@ namespace Symfony\Component\DomCrawler\Field;
  */
 class ChoiceFormField extends FormField
 {
+    /**
+     * @var string
+     */
     private $type;
+    /**
+     * @var Boolean
+     */
     private $multiple;
+    /**
+     * @var array
+     */
     private $options;
 
     /**
@@ -44,7 +53,7 @@ class ChoiceFormField extends FormField
     /**
      * Check if the current selected option is disabled
      *
-     * @return bool
+     * @return Boolean
      */
     public function isDisabled()
     {
@@ -62,8 +71,6 @@ class ChoiceFormField extends FormField
      *
      * @param string $value The value of the field
      *
-     * @throws \InvalidArgumentException When value type provided is not correct
-     *
      * @api
      */
     public function select($value)
@@ -74,7 +81,7 @@ class ChoiceFormField extends FormField
     /**
      * Ticks a checkbox.
      *
-     * @throws \InvalidArgumentException When value type provided is not correct
+     * @throws \LogicException When the type provided is not correct
      *
      * @api
      */
@@ -90,7 +97,7 @@ class ChoiceFormField extends FormField
     /**
      * Ticks a checkbox.
      *
-     * @throws \InvalidArgumentException When value type provided is not correct
+     * @throws \LogicException When the type provided is not correct
      *
      * @api
      */
@@ -248,7 +255,7 @@ class ChoiceFormField extends FormField
     /**
      * Returns option value with associated disabled flag
      *
-     * @param type $node
+     * @param \DOMNode $node
      *
      * @return array
      */

src/Symfony/Component/DomCrawler/Field/FormField.php

@@ -18,11 +18,29 @@ namespace Symfony\Component\DomCrawler\Field;
  */
 abstract class FormField
 {
+    /**
+     * @var \DOMNode
+     */
     protected $node;
+    /**
+     * @var string
+     */
     protected $name;
+    /**
+     * @var string
+     */
     protected $value;
+    /**
+     * @var \DOMDocument
+     */
     protected $document;
+    /**
+     * @var \DOMXPath
+     */
     protected $xpath;
+    /**
+     * @var Boolean
+     */
     protected $disabled;
 
     /**
@@ -87,6 +105,11 @@ abstract class FormField
         return true;
     }
 
+    /**
+     * Check if the current field is disabled
+     *
+     * @return Boolean
+     */
     public function isDisabled()
     {
         return $this->node->hasAttribute('disabled');

src/Symfony/Component/DomCrawler/Form.php

@@ -22,7 +22,13 @@ use Symfony\Component\DomCrawler\Field\FormField;
  */
 class Form extends Link implements \ArrayAccess
 {
+    /**
+     * @var \DOMNode
+     */
     private $button;
+    /**
+     * @var Field\FormField[]
+     */
     private $fields;
 
     /**
@@ -58,6 +64,8 @@ class Form extends Link implements \ArrayAccess
      *
      * @param array $values An array of field values
      *
+     * @return Form
+     *
      * @api
      */
     public function setValues(array $values)
@@ -254,8 +262,6 @@ class Form extends Link implements \ArrayAccess
      *
      * @param Field\FormField $field The field
      *
-     * @return FormField The field instance
-     *
      * @api
      */
     public function set(Field\FormField $field)

src/Symfony/Component/DomCrawler/Link.php

@@ -20,8 +20,17 @@ namespace Symfony\Component\DomCrawler;
  */
 class Link
 {
+    /**
+     * @var \DOMNode A \DOMNode instance
+     */
     protected $node;
+    /**
+     * @var string The method to use for the link
+     */
     protected $method;
+    /**
+     * @var string The URI of the page where the link is embedded (or the base href)
+     */
     protected $currentUri;
 
     /**
@@ -31,7 +40,7 @@ class Link
      * @param string   $currentUri The URI of the page where the link is embedded (or the base href)
      * @param string   $method     The method to use for the link (get by default)
      *
-     * @throws \LogicException if the node is not a link
+     * @throws \InvalidArgumentException if the node is not a link
      *
      * @api
      */
@@ -90,7 +99,7 @@ class Link
         }
 
         // only an anchor
-        if ('#' ===  $uri[0]) {
+        if ('#' === $uri[0]) {
             $baseUri = $this->currentUri;
             if (false !== $pos = strpos($baseUri, '#')) {
                 $baseUri = substr($baseUri, 0, $pos);
@@ -120,11 +129,23 @@ class Link
         return substr($this->currentUri, 0, strrpos($this->currentUri, '/') + 1).$uri;
     }
 
+    /**
+     * Returns raw uri data
+     *
+     * @return string
+     */
     protected function getRawUri()
     {
         return $this->node->getAttribute('href');
     }
 
+    /**
+     * Sets current \DOMNode instance
+     *
+     * @param \DOMNode $node A \DOMNode instance
+     *
+     * @throws \LogicException If given node is not an anchor
+     */
     protected function setNode(\DOMNode $node)
     {
         if ('a' != $node->nodeName) {