Add documentation and test for FormHelper::select()

An alternate syntax was undocumented and untested.  Fix that.
Refs #1794

lib/Cake/Test/Case/View/Helper/FormHelperTest.php

@@ -3441,6 +3441,27 @@ class FormHelperTest extends CakeTestCase {
 		);
 		$this->assertTags($result, $expected);
 
+		$options = array(
+			array('value' => 'first', 'name' => 'First'),
+			array('value' => 'first', 'name' => 'Another First'),
+		);
+		$result = $this->Form->select(
+			'Model.field',
+			$options,
+			array('escape' => false, 'empty' => false)
+		);
+		$expected = array(
+			'select' => array('name' => 'data[Model][field]', 'id' => 'ModelField'),
+			array('option' => array('value' => 'first')),
+			'First',
+			'/option',
+			array('option' => array('value' => 'first')),
+			'Another First',
+			'/option',
+			'/select'
+		);
+		$this->assertTags($result, $expected);
+
 		$this->Form->request->data = array('Model' => array('contact_id' => 228));
 		$result = $this->Form->select(
 			'Model.contact_id',

lib/Cake/View/Helper/FormHelper.php

@@ -1245,7 +1245,7 @@ class FormHelper extends AppHelper {
  * - `value` - indicate a value that is should be checked
  * - `label` - boolean to indicate whether or not labels for widgets show be displayed
  * - `hiddenField` - boolean to indicate if you want the results of radio() to include
- *	a hidden input with a value of ''. This is useful for creating radio sets that non-continuous
+ *    a hidden input with a value of ''. This is useful for creating radio sets that non-continuous
  *
  * @param string $fieldName Name of a field, like this "Modelname.fieldname"
  * @param array $options Radio button options array.
@@ -1694,6 +1694,16 @@ class FormHelper extends AppHelper {
  * In the above `2 => 'fred'` will not generate an option element.  You should enable the `showParents`
  * attribute to show the fred option.
  *
+ * If you have multiple options that need to have the same value attribute, you can
+ * use an array of arrays to express this:
+ *
+ * {{{
+ * $options = array(
+ *		array('name' => 'United states', 'value' => 'USA'),
+ *		array('name' => 'USA', 'value' => 'USA'),
+ * );
+ * }}}
+ *
  * @param string $fieldName Name attribute of the SELECT
  * @param array $options Array of the OPTION elements (as 'value'=>'Text' pairs) to be used in the
  *	SELECT element