[giow] (2) Document the setter on <select> and <select>.options

Fixing http://www.w3.org/Bugs/Public/show_bug.cgi?id=12639 git-svn-id: http://svn.whatwg.org/webapps@6360 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · Aug 3, 2011 · 828c091 · 828c091
1 parent 89a61cf
commit 828c091
Show file tree

Hide file tree

Showing 3 changed files with 103 additions and 3 deletions.
diff --git a/complete.html b/complete.html
@@ -8233,6 +8233,7 @@ <h5 id=htmloptionscollection-0><span class=secno>2.8.2.3 </span>HTMLOptionsColle
   // inherits <span title=dom-HTMLCollection-item>item</span>()
            attribute unsigned long <a href=#dom-htmloptionscollection-length title=dom-HTMLOptionsCollection-length>length</a>; // overrides inherited length
   caller getter object? <a href=#dom-htmloptionscollection-nameditem title=dom-HTMLOptionsCollection-namedItem>namedItem</a>(in DOMString name); // overrides inherited namedItem()
+  <a href=#dom-htmloptionscollection-setter title=dom-HTMLOptionsCollection-setter>setter creator</a> void (in unsigned long index, in <a href=#htmloptionelement>HTMLOptionElement</a> option);
   void <a href=#dom-htmloptionscollection-add title=dom-HTMLOptionsCollection-add>add</a>(in <a href=#htmlelement>HTMLElement</a> element, in optional <a href=#htmlelement>HTMLElement</a>? before);
   void <a href=#dom-htmloptionscollection-add title=dom-HTMLOptionsCollection-add>add</a>(in <a href=#htmlelement>HTMLElement</a> element, in long before);
   void <a href=#dom-htmloptionscollection-remove title=dom-HTMLOptionsCollection-remove>remove</a>(in long index);
@@ -8308,7 +8309,7 @@ <h5 id=htmloptionscollection-0><span class=secno>2.8.2.3 </span>HTMLOptionsColle
   <code><a href=#htmloptionscollection>HTMLOptionsCollection</a></code> is rooted, where <var title="">n</var> is the difference between the two numbers (new
   value minus old value). Mutation events must be fired as if a
   <code><a href=#documentfragment>DocumentFragment</a></code> containing the new <code><a href=#the-option-element>option</a></code>
-  elements had been inserted.  If the new value is lower, then the
+  elements had been inserted. If the new value is lower, then the
   last <var title="">n</var> nodes in the collection must be removed
   from their parent nodes, where <var title="">n</var> is the
   difference between the two numbers (old value minus new value).</p>
@@ -8342,6 +8343,28 @@ <h5 id=htmloptionscollection-0><span class=secno>2.8.2.3 </span>HTMLOptionsColle
 
    <li>Return that <code><a href=#nodelist>NodeList</a></code> object.</li>
 
+  </ol><p>When the user agent is to <dfn id=dom-htmloptionscollection-setter title=dom-HTMLOptionsCollection-setter>set the value of a new
+  indexed property</dfn> for a given property index <var title="">index</var> to a new value <var title="">value</var>, it
+  must run the following algorithm:</p>
+
+  <ol><li><p>Let <var title="">length</var> be the number of nodes
+   <a href=#represented-by-the-collection>represented by the collection</a>.</li>
+
+   <li><p>Let <var title="">n</var> be <var title="">index</var> minus
+   <var title="">length</var>.</li>
+
+   <li><p>If <var title="">n</var> is greater than one, then append
+   <var title="">n</var> new <code><a href=#the-option-element>option</a></code> elements with no
+   attributes and no child nodes to the <code><a href=#the-select-element>select</a></code> element on
+   which the <code><a href=#htmloptionscollection>HTMLOptionsCollection</a></code> is rooted. Mutation
+   events must be fired as if a <code><a href=#documentfragment>DocumentFragment</a></code>
+   containing the new <code><a href=#the-option-element>option</a></code> elements had been
+   inserted.</li>
+
+   <li><p>If <var title="">n</var> is zero, append <var title="">value</var> to the <code><a href=#the-select-element>select</a></code> element. Otherwise,
+   replace the <var title="">index</var>th element in the collection
+   by <var title="">value</var>.</li>
+
   </ol><p>The <dfn id=dom-htmloptionscollection-add title=dom-HTMLOptionsCollection-add><code>add(<var title="">element</var>, <var title="">before</var>)</code></dfn>
   method must act according to the following algorithm:</p>
 
@@ -48179,6 +48202,7 @@ <h4 id=the-select-element><span class=secno>4.10.9 </span>The <dfn><code>select<
   void <a href=#dom-select-add title=dom-select-add>add</a>(in <a href=#htmlelement>HTMLElement</a> element, in optional <a href=#htmlelement>HTMLElement</a>? before);
   void <a href=#dom-select-add title=dom-select-add>add</a>(in <a href=#htmlelement>HTMLElement</a> element, in long before);
   void <a href=#dom-select-remove title=dom-select-remove>remove</a>(in long index);
+  <a href=#dom-htmloptionscollection-setter title=dom-HTMLOptionsCollection-setter>setter creator</a> void (in unsigned long index, in <a href=#htmloptionelement>HTMLOptionElement</a> option);
 
   readonly attribute <a href=#htmlcollection>HTMLCollection</a> <a href=#dom-select-selectedoptions title=dom-select-selectedOptions>selectedOptions</a>;
            attribute long <a href=#dom-select-selectedindex title=dom-select-selectedIndex>selectedIndex</a>;
@@ -48483,6 +48507,12 @@ <h4 id=the-select-element><span class=secno>4.10.9 </span>The <dfn><code>select<
   returned by the method of the same name on the <code title=dom-select-options><a href=#dom-select-options>options</a></code> collection, when invoked
   with the same argument.</p>
 
+  <p>When the user agent is to <dfn id=dom-htmlselectelement-setter title=dom-HTMLSelectElement-setter>set the value of a new indexed
+  property</dfn> for a given property index <var title="">index</var>
+  to a new value <var title="">value</var>, it must instead <a href=#dom-htmloptionscollection-setter title=dom-HTMLOptionsCollection-setter>set the value of a new
+  indexed property</a> with the given property index <var title="">index</var> to the new value <var title="">value</var> on the
+  <code title=dom-select-options><a href=#dom-select-options>options</a></code> collection.</p>
+
   <p>Similarly, the <dfn id=dom-select-add title=dom-select-add><code>add()</code></dfn> and <dfn id=dom-select-remove title=dom-select-remove><code>remove()</code></dfn> methods must
   act like their namesake methods on that same <code title=dom-select-options><a href=#dom-select-options>options</a></code> collection.</p>
 

diff --git a/index b/index
@@ -8102,6 +8102,7 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E..
   // inherits <span title=dom-HTMLCollection-item>item</span>()
            attribute unsigned long <a href=#dom-htmloptionscollection-length title=dom-HTMLOptionsCollection-length>length</a>; // overrides inherited length
   caller getter object? <a href=#dom-htmloptionscollection-nameditem title=dom-HTMLOptionsCollection-namedItem>namedItem</a>(in DOMString name); // overrides inherited namedItem()
+  <a href=#dom-htmloptionscollection-setter title=dom-HTMLOptionsCollection-setter>setter creator</a> void (in unsigned long index, in <a href=#htmloptionelement>HTMLOptionElement</a> option);
   void <a href=#dom-htmloptionscollection-add title=dom-HTMLOptionsCollection-add>add</a>(in <a href=#htmlelement>HTMLElement</a> element, in optional <a href=#htmlelement>HTMLElement</a>? before);
   void <a href=#dom-htmloptionscollection-add title=dom-HTMLOptionsCollection-add>add</a>(in <a href=#htmlelement>HTMLElement</a> element, in long before);
   void <a href=#dom-htmloptionscollection-remove title=dom-HTMLOptionsCollection-remove>remove</a>(in long index);
@@ -8177,7 +8178,7 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E..
   <code><a href=#htmloptionscollection>HTMLOptionsCollection</a></code> is rooted, where <var title="">n</var> is the difference between the two numbers (new
   value minus old value). Mutation events must be fired as if a
   <code><a href=#documentfragment>DocumentFragment</a></code> containing the new <code><a href=#the-option-element>option</a></code>
-  elements had been inserted.  If the new value is lower, then the
+  elements had been inserted. If the new value is lower, then the
   last <var title="">n</var> nodes in the collection must be removed
   from their parent nodes, where <var title="">n</var> is the
   difference between the two numbers (old value minus new value).</p>
@@ -8211,6 +8212,28 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E..
 
    <li>Return that <code><a href=#nodelist>NodeList</a></code> object.</li>
 
+  </ol><p>When the user agent is to <dfn id=dom-htmloptionscollection-setter title=dom-HTMLOptionsCollection-setter>set the value of a new
+  indexed property</dfn> for a given property index <var title="">index</var> to a new value <var title="">value</var>, it
+  must run the following algorithm:</p>
+
+  <ol><li><p>Let <var title="">length</var> be the number of nodes
+   <a href=#represented-by-the-collection>represented by the collection</a>.</li>
+
+   <li><p>Let <var title="">n</var> be <var title="">index</var> minus
+   <var title="">length</var>.</li>
+
+   <li><p>If <var title="">n</var> is greater than one, then append
+   <var title="">n</var> new <code><a href=#the-option-element>option</a></code> elements with no
+   attributes and no child nodes to the <code><a href=#the-select-element>select</a></code> element on
+   which the <code><a href=#htmloptionscollection>HTMLOptionsCollection</a></code> is rooted. Mutation
+   events must be fired as if a <code><a href=#documentfragment>DocumentFragment</a></code>
+   containing the new <code><a href=#the-option-element>option</a></code> elements had been
+   inserted.</li>
+
+   <li><p>If <var title="">n</var> is zero, append <var title="">value</var> to the <code><a href=#the-select-element>select</a></code> element. Otherwise,
+   replace the <var title="">index</var>th element in the collection
+   by <var title="">value</var>.</li>
+
   </ol><p>The <dfn id=dom-htmloptionscollection-add title=dom-HTMLOptionsCollection-add><code>add(<var title="">element</var>, <var title="">before</var>)</code></dfn>
   method must act according to the following algorithm:</p>
 
@@ -48051,6 +48074,7 @@ You cannot submit this form when the field is incorrect.</samp></pre>
   void <a href=#dom-select-add title=dom-select-add>add</a>(in <a href=#htmlelement>HTMLElement</a> element, in optional <a href=#htmlelement>HTMLElement</a>? before);
   void <a href=#dom-select-add title=dom-select-add>add</a>(in <a href=#htmlelement>HTMLElement</a> element, in long before);
   void <a href=#dom-select-remove title=dom-select-remove>remove</a>(in long index);
+  <a href=#dom-htmloptionscollection-setter title=dom-HTMLOptionsCollection-setter>setter creator</a> void (in unsigned long index, in <a href=#htmloptionelement>HTMLOptionElement</a> option);
 
   readonly attribute <a href=#htmlcollection>HTMLCollection</a> <a href=#dom-select-selectedoptions title=dom-select-selectedOptions>selectedOptions</a>;
            attribute long <a href=#dom-select-selectedindex title=dom-select-selectedIndex>selectedIndex</a>;
@@ -48355,6 +48379,12 @@ You cannot submit this form when the field is incorrect.</samp></pre>
   returned by the method of the same name on the <code title=dom-select-options><a href=#dom-select-options>options</a></code> collection, when invoked
   with the same argument.</p>
 
+  <p>When the user agent is to <dfn id=dom-htmlselectelement-setter title=dom-HTMLSelectElement-setter>set the value of a new indexed
+  property</dfn> for a given property index <var title="">index</var>
+  to a new value <var title="">value</var>, it must instead <a href=#dom-htmloptionscollection-setter title=dom-HTMLOptionsCollection-setter>set the value of a new
+  indexed property</a> with the given property index <var title="">index</var> to the new value <var title="">value</var> on the
+  <code title=dom-select-options><a href=#dom-select-options>options</a></code> collection.</p>
+
   <p>Similarly, the <dfn id=dom-select-add title=dom-select-add><code>add()</code></dfn> and <dfn id=dom-select-remove title=dom-select-remove><code>remove()</code></dfn> methods must
   act like their namesake methods on that same <code title=dom-select-options><a href=#dom-select-options>options</a></code> collection.</p>
 

diff --git a/source b/source
@@ -8106,6 +8106,7 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E..
   // inherits <span title="dom-HTMLCollection-item">item</span>()
            attribute unsigned long <span title="dom-HTMLOptionsCollection-length">length</span>; // overrides inherited length
   caller getter object? <span title="dom-HTMLOptionsCollection-namedItem">namedItem</span>(in DOMString name); // overrides inherited namedItem()
+  <span title="dom-HTMLOptionsCollection-setter">setter creator</span> void (in unsigned long index, in <span>HTMLOptionElement</span> option);
   void <span title="dom-HTMLOptionsCollection-add">add</span>(in <span>HTMLElement</span> element, in optional <span>HTMLElement</span>? before);
   void <span title="dom-HTMLOptionsCollection-add">add</span>(in <span>HTMLElement</span> element, in long before);
   void <span title="dom-HTMLOptionsCollection-remove">remove</span>(in long index);
@@ -8188,7 +8189,7 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E..
   title="">n</var> is the difference between the two numbers (new
   value minus old value). Mutation events must be fired as if a
   <code>DocumentFragment</code> containing the new <code>option</code>
-  elements had been inserted.  If the new value is lower, then the
+  elements had been inserted. If the new value is lower, then the
   last <var title="">n</var> nodes in the collection must be removed
   from their parent nodes, where <var title="">n</var> is the
   difference between the two numbers (old value minus new value).</p>
@@ -8237,6 +8238,35 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E..
 
   </ol>
 
+  <p>When the user agent is to <dfn
+  title="dom-HTMLOptionsCollection-setter">set the value of a new
+  indexed property</dfn> for a given property index <var
+  title="">index</var> to a new value <var title="">value</var>, it
+  must run the following algorithm:</p>
+
+  <ol>
+
+   <li><p>Let <var title="">length</var> be the number of nodes
+   <span>represented by the collection</span>.</p></li>
+
+   <li><p>Let <var title="">n</var> be <var title="">index</var> minus
+   <var title="">length</var>.</p></li>
+
+   <li><p>If <var title="">n</var> is greater than one, then append
+   <var title="">n</var> new <code>option</code> elements with no
+   attributes and no child nodes to the <code>select</code> element on
+   which the <code>HTMLOptionsCollection</code> is rooted. Mutation
+   events must be fired as if a <code>DocumentFragment</code>
+   containing the new <code>option</code> elements had been
+   inserted.</p></li>
+
+   <li><p>If <var title="">n</var> is zero, append <var
+   title="">value</var> to the <code>select</code> element. Otherwise,
+   replace the <var title="">index</var>th element in the collection
+   by <var title="">value</var>.</p></li>
+
+  </ol>
+
   <p>The <dfn title="dom-HTMLOptionsCollection-add"><code>add(<var
   title="">element</var>, <var title="">before</var>)</code></dfn>
   method must act according to the following algorithm:</p>
@@ -53930,6 +53960,7 @@ You cannot submit this form when the field is incorrect.</samp></pre>
   void <span title="dom-select-add">add</span>(in <span>HTMLElement</span> element, in optional <span>HTMLElement</span>? before);
   void <span title="dom-select-add">add</span>(in <span>HTMLElement</span> element, in long before);
   void <span title="dom-select-remove">remove</span>(in long index);
+  <span title="dom-HTMLOptionsCollection-setter">setter creator</span> void (in unsigned long index, in <span>HTMLOptionElement</span> option);
 
   readonly attribute <span>HTMLCollection</span> <span title="dom-select-selectedOptions">selectedOptions</span>;
            attribute long <span title="dom-select-selectedIndex">selectedIndex</span>;
@@ -54293,6 +54324,15 @@ You cannot submit this form when the field is incorrect.</samp></pre>
   title="dom-select-options">options</code> collection, when invoked
   with the same argument.</p>
 
+  <p>When the user agent is to <dfn
+  title="dom-HTMLSelectElement-setter">set the value of a new indexed
+  property</dfn> for a given property index <var title="">index</var>
+  to a new value <var title="">value</var>, it must instead <span
+  title="dom-HTMLOptionsCollection-setter">set the value of a new
+  indexed property</span> with the given property index <var
+  title="">index</var> to the new value <var title="">value</var> on the
+  <code title="dom-select-options">options</code> collection.</p>
+
   <p>Similarly, the <dfn
   title="dom-select-add"><code>add()</code></dfn> and <dfn
   title="dom-select-remove"><code>remove()</code></dfn> methods must