[e] (0) Try to clarify how 'storage' events are sent.

Fixing https://www.w3.org/Bugs/Public/show_bug.cgi?id=19540
Affected topics: DOM APIs, HTML

git-svn-id: http://svn.whatwg.org/webapps@7592 340c8d12-0b0e-0410-8428-c7bf67bfef74

complete.html

@@ -85251,12 +85251,10 @@ <h4 id=the-storage-interface><span class=secno>11.2.1 </span>The <code><a href=#
   be emptied of all key/value pairs, if there are any. If there are
   none, then the method must do nothing.</p>
 
-  <p class=note>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are invoked, events
-  are fired on other <code><a href=#document>Document</a></code> objects that can access the
-  newly stored or removed data, as defined in the sections on the
-  <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code> and <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> attributes.</p> <!--
-  not normative, see the sections below for the normative statement
-  -->
+  <p class=note>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are invoked, events are fired on the
+  <code><a href=#window>Window</a></code> objecys of other <code><a href=#document>Document</a></code>s that can access the newly stored or
+  removed data, as defined in the sections on the <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code> and <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> attributes.</p> <!-- not normative, see the sections
+  below for the normative statement -->
 
   <p class=note>This specification does not require that the above
   methods wait until the data has been physically written to
@@ -85333,13 +85331,10 @@ <h4 id=the-sessionstorage-attribute><span class=secno>11.2.2 </span>The <code ti
   on, however, the two session storage areas must be considered
   separate, not affecting each other in any way.</p>
 
-  <p id=sessionStorageEvent>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are called on a
-  <code><a href=#storage-0>Storage</a></code> object <var title="">x</var> that is associated
-  with a session storage area, if the methods did something, then in
-  every <code><a href=#document>Document</a></code> object whose <code><a href=#window>Window</a></code>
-  object's <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code>
-  attribute's <code><a href=#storage-0>Storage</a></code> object is associated with the same
-  storage area, other than <var title="">x</var>, a <code title=event-storage><a href=#event-storage>storage</a></code> event must be fired, as <a href=#event-storage title=event-storage>described below</a>.</p>
+  <p id=sessionStorageEvent>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are called on a <code><a href=#storage-0>Storage</a></code> object <var title="">x</var> that is associated with a session storage area, if the methods did something,
+  then for every <code><a href=#document>Document</a></code> object whose <code><a href=#window>Window</a></code> object's <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code> attribute's <code><a href=#storage-0>Storage</a></code> object is
+  associated with the same storage area, other than <var title="">x</var>, <a href=#send-a-storage-notification>send a storage
+  notification</a>.
 
 
   <h4 id=the-localstorage-attribute><span class=secno>11.2.3 </span>The <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> attribute</h4>
@@ -85391,11 +85386,12 @@ <h4 id=the-localstorage-attribute><span class=secno>11.2.3 </span>The <code titl
 
   </ol><p id=localStorageEvent>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are called on a
   <code><a href=#storage-0>Storage</a></code> object <var title="">x</var> that is associated
-  with a local storage area, if the methods did something, then in
+  with a local storage area, if the methods did something, then for
   every <code><a href=#document>Document</a></code> object whose <code><a href=#window>Window</a></code>
   object's <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code>
   attribute's <code><a href=#storage-0>Storage</a></code> object is associated with the same
-  storage area, other than <var title="">x</var>, a <code title=event-storage><a href=#event-storage>storage</a></code> event must be fired, as <a href=#event-storage title=event-storage>described below</a>.</p>
+  storage area, other than <var title="">x</var>, <a href=#send-a-storage-notification>send a storage
+  notification</a>.
 
   <p id=localStorageMutex>Whenever the properties of a <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> attribute's
   <code><a href=#storage-0>Storage</a></code> object are to be examined, returned, set, or
@@ -85425,24 +85421,21 @@ <h5 id=security-localStorage><span class=secno>11.2.3.1 </span>Security</h5>
 
   <h4 id=the-storage-event><span class=secno>11.2.4 </span>The <code title=event-storage><a href=#event-storage>storage</a></code> event</h4>
 
-  <p>The <dfn id=event-storage title=event-storage><code>storage</code></dfn> event
-  is fired when a storage area changes, as described in the previous
-  two sections (<a href=#sessionStorageEvent>for session
-  storage</a>, <a href=#localStorageEvent>for local
-  storage</a>).</p>
+  <p>The <dfn id=event-storage title=event-storage><code>storage</code></dfn> event is fired on a
+  <code><a href=#document>Document</a></code>'s <code><a href=#window>Window</a></code> object when a storage area changes, as described in
+  the previous two sections (<a href=#sessionStorageEvent>for session storage</a>, <a href=#localStorageEvent>for local storage</a>).</p>
 
-  <p>When this happens, the user agent must <a href=#queue-a-task>queue a task</a> to <a href=#concept-event-fire title=concept-event-fire>fire</a> a <a href=#concept-events-trusted title=concept-events-trusted>trusted</a> event
-  with the name <code><a href=#storage-0>storage</a></code>, which does not bubble and is not cancelable, and which uses
-  the <code><a href=#storageevent>StorageEvent</a></code> interface, at each <code><a href=#window>Window</a></code> object whose
-  <code><a href=#document>Document</a></code> object has a <code><a href=#storage-0>Storage</a></code> object that is affected.</p>
+  <p>When a user agent is to <dfn id=send-a-storage-notification>send a storage notification</dfn> for a <code><a href=#document>Document</a></code>, the
+  user agent must <a href=#queue-a-task>queue a task</a> to <a href=#concept-event-fire title=concept-event-fire>fire</a> a <a href=#concept-events-trusted title=concept-events-trusted>trusted</a> event with the name <code><a href=#storage-0>storage</a></code>, which does
+  not bubble and is not cancelable, and which uses the <code><a href=#storageevent>StorageEvent</a></code> interface, at the
+  <code><a href=#document>Document</a></code> object's <code><a href=#window>Window</a></code> object.</p>
 
-  <p class=note>This includes <code><a href=#document>Document</a></code> objects that are
-  not <a href=#fully-active>fully active</a>, but events fired on those are ignored
-  by the <a href=#event-loop>event loop</a> until the <code><a href=#document>Document</a></code>
-  becomes <a href=#fully-active>fully active</a> again.</p>
+  <p class=note>Such a <code><a href=#document>Document</a></code> object is not necessarily <a href=#fully-active>fully active</a>,
+  but events fired on such objects are ignored by the <a href=#event-loop>event loop</a> until the
+  <code><a href=#document>Document</a></code> becomes <a href=#fully-active>fully active</a> again.</p>
 
-  <p>The <a href=#task-source>task source</a> for this task is the <a href=#dom-manipulation-task-source>DOM
-  manipulation task source</a>.</p>
+  <p>The <a href=#task-source>task source</a> for these tasks is the <a href=#dom-manipulation-task-source>DOM manipulation task
+  source</a>.</p>
 
   <p>If the event is being fired due to an invocation of the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code> or <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code> methods, the
   event must have its <code title=dom-StorageEvent-key><a href=#dom-storageevent-key>key</a></code>
@@ -104395,6 +104388,7 @@ <h2 class=no-num id=references>References</h2><!--REFS-->
   James Perrett,
   James Robinson,
   Jamie Lokier,
+  Janusz Majnert,
   Jan-Klaas Kollhof,
   Jason Duell,
   Jason Kersey,

index

@@ -85251,12 +85251,10 @@ callback <dfn id=portcollectioncallback>PortCollectionCallback</dfn> = void (<a
   be emptied of all key/value pairs, if there are any. If there are
   none, then the method must do nothing.</p>
 
-  <p class=note>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are invoked, events
-  are fired on other <code><a href=#document>Document</a></code> objects that can access the
-  newly stored or removed data, as defined in the sections on the
-  <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code> and <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> attributes.</p> <!--
-  not normative, see the sections below for the normative statement
-  -->
+  <p class=note>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are invoked, events are fired on the
+  <code><a href=#window>Window</a></code> objecys of other <code><a href=#document>Document</a></code>s that can access the newly stored or
+  removed data, as defined in the sections on the <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code> and <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> attributes.</p> <!-- not normative, see the sections
+  below for the normative statement -->
 
   <p class=note>This specification does not require that the above
   methods wait until the data has been physically written to
@@ -85333,13 +85331,10 @@ interface <dfn id=windowsessionstorage>WindowSessionStorage</dfn> {
   on, however, the two session storage areas must be considered
   separate, not affecting each other in any way.</p>
 
-  <p id=sessionStorageEvent>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are called on a
-  <code><a href=#storage-0>Storage</a></code> object <var title="">x</var> that is associated
-  with a session storage area, if the methods did something, then in
-  every <code><a href=#document>Document</a></code> object whose <code><a href=#window>Window</a></code>
-  object's <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code>
-  attribute's <code><a href=#storage-0>Storage</a></code> object is associated with the same
-  storage area, other than <var title="">x</var>, a <code title=event-storage><a href=#event-storage>storage</a></code> event must be fired, as <a href=#event-storage title=event-storage>described below</a>.</p>
+  <p id=sessionStorageEvent>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are called on a <code><a href=#storage-0>Storage</a></code> object <var title="">x</var> that is associated with a session storage area, if the methods did something,
+  then for every <code><a href=#document>Document</a></code> object whose <code><a href=#window>Window</a></code> object's <code title=dom-sessionStorage><a href=#dom-sessionstorage>sessionStorage</a></code> attribute's <code><a href=#storage-0>Storage</a></code> object is
+  associated with the same storage area, other than <var title="">x</var>, <a href=#send-a-storage-notification>send a storage
+  notification</a>.
 
 
   <h4 id=the-localstorage-attribute><span class=secno>11.2.3 </span>The <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> attribute</h4>
@@ -85391,11 +85386,12 @@ interface <dfn id=windowlocalstorage>WindowLocalStorage</dfn> {
 
   </ol><p id=localStorageEvent>When the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code>, <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code>, and <code title=dom-Storage-clear><a href=#dom-storage-clear>clear()</a></code> methods are called on a
   <code><a href=#storage-0>Storage</a></code> object <var title="">x</var> that is associated
-  with a local storage area, if the methods did something, then in
+  with a local storage area, if the methods did something, then for
   every <code><a href=#document>Document</a></code> object whose <code><a href=#window>Window</a></code>
   object's <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code>
   attribute's <code><a href=#storage-0>Storage</a></code> object is associated with the same
-  storage area, other than <var title="">x</var>, a <code title=event-storage><a href=#event-storage>storage</a></code> event must be fired, as <a href=#event-storage title=event-storage>described below</a>.</p>
+  storage area, other than <var title="">x</var>, <a href=#send-a-storage-notification>send a storage
+  notification</a>.
 
   <p id=localStorageMutex>Whenever the properties of a <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> attribute's
   <code><a href=#storage-0>Storage</a></code> object are to be examined, returned, set, or
@@ -85425,24 +85421,21 @@ interface <dfn id=windowlocalstorage>WindowLocalStorage</dfn> {
 
   <h4 id=the-storage-event><span class=secno>11.2.4 </span>The <code title=event-storage><a href=#event-storage>storage</a></code> event</h4>
 
-  <p>The <dfn id=event-storage title=event-storage><code>storage</code></dfn> event
-  is fired when a storage area changes, as described in the previous
-  two sections (<a href=#sessionStorageEvent>for session
-  storage</a>, <a href=#localStorageEvent>for local
-  storage</a>).</p>
+  <p>The <dfn id=event-storage title=event-storage><code>storage</code></dfn> event is fired on a
+  <code><a href=#document>Document</a></code>'s <code><a href=#window>Window</a></code> object when a storage area changes, as described in
+  the previous two sections (<a href=#sessionStorageEvent>for session storage</a>, <a href=#localStorageEvent>for local storage</a>).</p>
 
-  <p>When this happens, the user agent must <a href=#queue-a-task>queue a task</a> to <a href=#concept-event-fire title=concept-event-fire>fire</a> a <a href=#concept-events-trusted title=concept-events-trusted>trusted</a> event
-  with the name <code><a href=#storage-0>storage</a></code>, which does not bubble and is not cancelable, and which uses
-  the <code><a href=#storageevent>StorageEvent</a></code> interface, at each <code><a href=#window>Window</a></code> object whose
-  <code><a href=#document>Document</a></code> object has a <code><a href=#storage-0>Storage</a></code> object that is affected.</p>
+  <p>When a user agent is to <dfn id=send-a-storage-notification>send a storage notification</dfn> for a <code><a href=#document>Document</a></code>, the
+  user agent must <a href=#queue-a-task>queue a task</a> to <a href=#concept-event-fire title=concept-event-fire>fire</a> a <a href=#concept-events-trusted title=concept-events-trusted>trusted</a> event with the name <code><a href=#storage-0>storage</a></code>, which does
+  not bubble and is not cancelable, and which uses the <code><a href=#storageevent>StorageEvent</a></code> interface, at the
+  <code><a href=#document>Document</a></code> object's <code><a href=#window>Window</a></code> object.</p>
 
-  <p class=note>This includes <code><a href=#document>Document</a></code> objects that are
-  not <a href=#fully-active>fully active</a>, but events fired on those are ignored
-  by the <a href=#event-loop>event loop</a> until the <code><a href=#document>Document</a></code>
-  becomes <a href=#fully-active>fully active</a> again.</p>
+  <p class=note>Such a <code><a href=#document>Document</a></code> object is not necessarily <a href=#fully-active>fully active</a>,
+  but events fired on such objects are ignored by the <a href=#event-loop>event loop</a> until the
+  <code><a href=#document>Document</a></code> becomes <a href=#fully-active>fully active</a> again.</p>
 
-  <p>The <a href=#task-source>task source</a> for this task is the <a href=#dom-manipulation-task-source>DOM
-  manipulation task source</a>.</p>
+  <p>The <a href=#task-source>task source</a> for these tasks is the <a href=#dom-manipulation-task-source>DOM manipulation task
+  source</a>.</p>
 
   <p>If the event is being fired due to an invocation of the <code title=dom-Storage-setItem><a href=#dom-storage-setitem>setItem()</a></code> or <code title=dom-Storage-removeItem><a href=#dom-storage-removeitem>removeItem()</a></code> methods, the
   event must have its <code title=dom-StorageEvent-key><a href=#dom-storageevent-key>key</a></code>
@@ -104395,6 +104388,7 @@ if (s = prompt('What is your name?')) {
   James Perrett,
   James Robinson,
   Jamie Lokier,
+  Janusz Majnert,
   Jan-Klaas Kollhof,
   Jason Duell,
   Jason Kersey,