val(): Update select multiple no selected statement for 3.0. Fixes #828

Author: kswedberg

entries/val.xml

@@ -11,7 +11,8 @@
     </signature>
     <desc>Get the current value of the first element in the set of matched elements.</desc>
     <longdesc>
-      <p>The <code>.val()</code> method is primarily used to get the values of form elements such as <code>input</code>, <code>select</code> and <code>textarea</code>. When the first element in the collection is a <code>select-multiple</code> (i.e., a <code>select</code> element with the <code>multiple</code> attribute set), it returns an array containing the value of each selected option, or <code>null</code> if no options are selected. When called on an empty collection, it returns <code>undefined</code>.</p>
+      <p>The <code>.val()</code> method is primarily used to get the values of form elements such as <code>input</code>, <code>select</code> and <code>textarea</code>. When called on an empty collection, it returns <code>undefined</code>.</p>
+      <p>When the first element in the collection is a <code>select-multiple</code> (i.e., a <code>select</code> element with the <code>multiple</code> attribute set), <code>.val()</code> returns an array containing the value of each selected option. <strong>As of jQuery 3.0</strong>, if no options are selected, it returns an empty array; <strong>prior to jQuery 3.0</strong>, it returns <code>null</code>.</p>
       <p>For selects and checkboxes, you can also use the <a href="/selected-selector/">:selected</a> and <a href="/checked-selector/">:checked</a> selectors to get at values, for example:</p>
       <pre><code>
 // Get the value from a dropdown select
@@ -27,7 +28,7 @@ $( "input:checkbox:checked" ).val();
 $( "input:radio[name=bar]:checked" ).val();
       </code></pre>
       <div class="warning">
-        <p><strong>Note: </strong> At present, using <code>.val()</code> on textarea elements strips carriage return characters from the browser-reported value. When this value is sent to the server via XHR however, carriage returns are preserved (or added by browsers which do not include them in the raw value). A workaround for this issue can be achieved using a valHook as follows:</p>
+        <p><strong>Note: </strong> At present, using <code>.val()</code> on textarea elements strips carriage return characters from the browser-reported value. When this value is sent to the server via XHR, however, carriage returns are preserved (or added by browsers which do not include them in the raw value). A workaround for this issue can be achieved using a valHook as follows:</p>
       </div>
       <pre><code>
 $.valHooks.textarea = {
@@ -115,17 +116,17 @@ $( "input" )
       <added>1.4</added>
       <argument name="function" type="Function">
         <argument name="index" type="Integer" />
-        <argument name="value" type="String" />     
-        <return type="String" />         
+        <argument name="value" type="String" />
+        <return type="String" />
         <desc>A function returning the value to set. <code>this</code> is the current element. Receives the index position of the element in the set and the old value as arguments.</desc>
       </argument>
     </signature>
     <desc>Set the value of each element in the set of matched elements.</desc>
     <longdesc>
       <p>This method is typically used to set the values of form fields. </p>
-      <p><code>val()</code> allows you to pass an array of element values. This is useful when working on a jQuery object containing elements like <code>&lt;input type="checkbox"&gt;</code>, <code>&lt;input type="radio"&gt;</code>, and <code>&lt;option&gt;</code>s inside of a <code>&lt;select&gt;</code>. In this case, the <code>input</code>s and the <code>option</code>s having a <code>value</code> that matches one of the elements of the array will be checked or selected while those having a <code>value</code> that don't match one of the elements of the array will be unchecked or unselected, depending on the type. In case of <code>&lt;input type="radio"&gt;</code>s that are part of a radio group and <code>&lt;select&gt;</code>s, any previously selected element will be deselected.</p>
+      <p><code>val()</code> allows you to pass an array of element values. This is useful when working on a jQuery object containing elements like <code>&lt;input type="checkbox"&gt;</code>, <code>&lt;input type="radio"&gt;</code>, and <code>&lt;option&gt;</code>s inside of a <code>&lt;select&gt;</code>. In this case, the <code>input</code>s and the <code>option</code>s having a <code>value</code> that matches one of the elements of the array will be checked or selected while those having a <code>value</code> that doesn't match one of the elements of the array will be unchecked or unselected, depending on the type. In the case of <code>&lt;input type="radio"&gt;</code>s that are part of a radio group and <code>&lt;select&gt;</code>s, any previously selected element will be deselected.</p>
       <p>Setting values using this method (or using the native <code>value</code> property) does not cause the dispatch of the <code>change</code> event. For this reason, the relevant event handlers will not be executed. If you want to execute them, you should call <code>.trigger( "change" )</code> after setting the value.</p>
-      <p>The <code>.val()</code> method allows us to set the value by passing in a function. As of jQuery 1.4, the function is passed two arguments, the current element's index and its current value: </p>
+      <p>The <code>.val()</code> method allows settting the value by passing in a function. As of jQuery 1.4, the function is passed two arguments, the current element's index and its current value: </p>
       <pre><code>
 $( "input:text.items" ).val(function( index, value ) {
   return value + " " + this.className;