minor symfony#29181 [Form] Minor fixes in docs and cs (HeahDude)

This PR was merged into the 2.8 branch.

Discussion
----------

[Form] Minor fixes in docs and cs

| Q             | A
| ------------- | ---
| Branch?       | 2.8
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | ~
| License       | MIT
| Doc PR        | ~

Commits
-------

de40f5d [Form] Minor fixes in docs and cs

Author: nicolas-grekas

src/Symfony/Component/Form/Form.php

@@ -32,24 +32,26 @@
  *
  *   (1) the "model" format required by the form's object
  *   (2) the "normalized" format for internal processing
- *   (3) the "view" format used for display
+ *   (3) the "view" format used for display simple fields
+ *       or map children model data for compound fields
  *
  * A date field, for example, may store a date as "Y-m-d" string (1) in the
  * object. To facilitate processing in the field, this value is normalized
  * to a DateTime object (2). In the HTML representation of your form, a
- * localized string (3) is presented to and modified by the user.
+ * localized string (3) may be presented to and modified by the user, or it could be an array of values
+ * to be mapped to choices fields.
  *
  * In most cases, format (1) and format (2) will be the same. For example,
  * a checkbox field uses a Boolean value for both internal processing and
- * storage in the object. In these cases you simply need to set a value
+ * storage in the object. In these cases you simply need to set a view
  * transformer to convert between formats (2) and (3). You can do this by
  * calling addViewTransformer().
  *
  * In some cases though it makes sense to make format (1) configurable. To
  * demonstrate this, let's extend our above date field to store the value
  * either as "Y-m-d" string or as timestamp. Internally we still want to
  * use a DateTime object for processing. To convert the data from string/integer
- * to DateTime you can set a normalization transformer by calling
+ * to DateTime you can set a model transformer by calling
  * addModelTransformer(). The normalized data is then converted to the displayed
  * data as described before.
  *
@@ -218,7 +220,7 @@ public function getPropertyPath()
         }
 
         if (null === $this->getName() || '' === $this->getName()) {
-            return;
+            return null;
         }
 
         $parent = $this->parent;
@@ -341,8 +343,8 @@ public function setData($modelData)
             $modelData = $event->getData();
         }
 
-        // Treat data as strings unless a value transformer exists
-        if (!$this->config->getViewTransformers() && !$this->config->getModelTransformers() && is_scalar($modelData)) {
+        // Treat data as strings unless a transformer exists
+        if (is_scalar($modelData) && !$this->config->getViewTransformers() && !$this->config->getModelTransformers()) {
             $modelData = (string) $modelData;
         }
 
@@ -1068,7 +1070,7 @@ public function createView(FormView $parent = null)
     }
 
     /**
-     * Normalizes the value if a normalization transformer is set.
+     * Normalizes the value if a model transformer is set.
      *
      * @param mixed $value The value to transform
      *
@@ -1090,7 +1092,7 @@ private function modelToNorm($value)
     }
 
     /**
-     * Reverse transforms a value if a normalization transformer is set.
+     * Reverse transforms a value if a model transformer is set.
      *
      * @param string $value The value to reverse transform
      *
@@ -1114,7 +1116,7 @@ private function normToModel($value)
     }
 
     /**
-     * Transforms the value if a value transformer is set.
+     * Transforms the value if a view transformer is set.
      *
      * @param mixed $value The value to transform
      *
@@ -1145,7 +1147,7 @@ private function normToView($value)
     }
 
     /**
-     * Reverse transforms a value if a value transformer is set.
+     * Reverse transforms a value if a view transformer is set.
      *
      * @param string $value The value to reverse transform
      *

src/Symfony/Component/Form/NativeRequestHandler.php

@@ -15,7 +15,7 @@
 use Symfony\Component\Form\Util\ServerParams;
 
 /**
- * A request handler using PHP's super globals $_GET, $_POST and $_SERVER.
+ * A request handler using PHP super globals $_GET, $_POST and $_SERVER.
  *
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
@@ -213,7 +213,7 @@ private static function stripEmptyFiles($data)
 
         if (self::$fileKeys === $keys) {
             if (UPLOAD_ERR_NO_FILE === $data['error']) {
-                return;
+                return null;
             }
 
             return $data;

src/Symfony/Component/Form/Util/FormUtil.php

@@ -27,7 +27,7 @@ private function __construct()
      * Returns whether the given data is empty.
      *
      * This logic is reused multiple times throughout the processing of
-     * a form and needs to be consistent. PHP's keyword `empty` cannot
+     * a form and needs to be consistent. PHP keyword `empty` cannot
      * be used as it also considers 0 and "0" to be empty.
      *
      * @param mixed $data

src/Symfony/Component/Form/Util/OrderedHashMap.php

@@ -128,7 +128,7 @@ public function offsetSet($key, $value)
                 $key = array() === $this->orderedKeys
                     // If the array is empty, use 0 as key
                     ? 0
-                    // Imitate PHP's behavior of generating a key that equals
+                    // Imitate PHP behavior of generating a key that equals
                     // the highest existing integer key + 1
                     : 1 + (int) max($this->orderedKeys);
             }

src/Symfony/Component/Form/Util/OrderedHashMapIterator.php

@@ -56,8 +56,6 @@ class OrderedHashMapIterator implements \Iterator
     private $current;
 
     /**
-     * Creates a new iterator.
-     *
      * @param array $elements       The elements of the map, indexed by their
      *                              keys
      * @param array $orderedKeys    The keys of the map in the order in which
@@ -84,7 +82,7 @@ public function __construct(array &$elements, array &$orderedKeys, array &$manag
      */
     public function __destruct()
     {
-        // Use array_splice() instead of isset() to prevent holes in the
+        // Use array_splice() instead of unset() to prevent holes in the
         // array indices, which would break the initialization of $cursorId
         array_splice($this->managedCursors, $this->cursorId, 1);
     }