[e] (0) Explain the appcache API more.

Fixing http://www.w3.org/Bugs/Public/show_bug.cgi?id=12967

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

complete.html

@@ -67621,13 +67621,26 @@ <h4 id=application-cache-api><span class=secno>6.6.9 </span>Application cache AP
 
     <p>Throws an <code><a href=#invalid_state_err>INVALID_STATE_ERR</a></code> exception if there is no application cache to update.</p>
 
+    <p>Calling this method is not usually necessary, as user agents
+    will generally take care of updating <a href=#application-cache title="application
+    cache">application caches</a> automatically.</p>
+
+    <p>The method can be useful in situations such as long-lived
+    applications. For example, a Web mail application might stay open
+    in a browser tab for weeks at a time. Such an application could
+    want to test for updates each day.</p>
+
    </dd>
 
    <dt><var title="">cache</var> . <code title=dom-appcache-abort><a href=#dom-appcache-abort>abort</a></code>()</dt>
    <dd>
 
     <p>Cancels the <a href=#application-cache-download-process>application cache download process</a>.</p>
 
+    <p>This method is intended to be used by Web application showing
+    their own caching progress UI, in case the user wants to stop the
+    update (e.g. because bandwidth is limited).</p>
+
    </dd>
 
    <dt><var title="">cache</var> . <code title=dom-appcache-swapCache><a href=#dom-appcache-swapcache>swapCache</a></code>()</dt>
@@ -67643,6 +67656,18 @@ <h4 id=application-cache-api><span class=secno>6.6.9 </span>Application cache AP
     that subsequent requests for cached resources will obtain the
     newer copies.</p>
 
+    <p>The <code title=event-appcache-updateready><a href=#event-appcache-updateready>updateready</a></code>
+    event will fire before this method can be called. Once it fires,
+    the Web application can, at its leisure, call this method to
+    switch the underlying cache to the one with the more recent
+    updates. To make proper use of this, applications have to be able
+    to bring the new features into play; for example, reloading
+    scripts to enable new features.</p>
+
+    <p>An easier alternative to <code title=dom-appcache-swapCache><a href=#dom-appcache-swapcache>swapCache()</a></code> is just to
+    reload the entire page at a time suitable for the user, using
+    <code title=dom-location-reload><a href=#dom-location-reload>location.reload()</a></code>.</p>
+
    </dd>
 
   </dl><div class=impl>

index

@@ -67500,13 +67500,26 @@ NETWORK:
 
     <p>Throws an <code><a href=#invalid_state_err>INVALID_STATE_ERR</a></code> exception if there is no application cache to update.</p>
 
+    <p>Calling this method is not usually necessary, as user agents
+    will generally take care of updating <a href=#application-cache title="application
+    cache">application caches</a> automatically.</p>
+
+    <p>The method can be useful in situations such as long-lived
+    applications. For example, a Web mail application might stay open
+    in a browser tab for weeks at a time. Such an application could
+    want to test for updates each day.</p>
+
    </dd>
 
    <dt><var title="">cache</var> . <code title=dom-appcache-abort><a href=#dom-appcache-abort>abort</a></code>()</dt>
    <dd>
 
     <p>Cancels the <a href=#application-cache-download-process>application cache download process</a>.</p>
 
+    <p>This method is intended to be used by Web application showing
+    their own caching progress UI, in case the user wants to stop the
+    update (e.g. because bandwidth is limited).</p>
+
    </dd>
 
    <dt><var title="">cache</var> . <code title=dom-appcache-swapCache><a href=#dom-appcache-swapcache>swapCache</a></code>()</dt>
@@ -67522,6 +67535,18 @@ NETWORK:
     that subsequent requests for cached resources will obtain the
     newer copies.</p>
 
+    <p>The <code title=event-appcache-updateready><a href=#event-appcache-updateready>updateready</a></code>
+    event will fire before this method can be called. Once it fires,
+    the Web application can, at its leisure, call this method to
+    switch the underlying cache to the one with the more recent
+    updates. To make proper use of this, applications have to be able
+    to bring the new features into play; for example, reloading
+    scripts to enable new features.</p>
+
+    <p>An easier alternative to <code title=dom-appcache-swapCache><a href=#dom-appcache-swapcache>swapCache()</a></code> is just to
+    reload the entire page at a time suitable for the user, using
+    <code title=dom-location-reload><a href=#dom-location-reload>location.reload()</a></code>.</p>
+
    </dd>
 
   </dl><div class=impl>

source

@@ -76840,13 +76840,26 @@ NETWORK:
 
     <p>Throws an <code>INVALID_STATE_ERR</code> exception if there is no application cache to update.</p>
 
+    <p>Calling this method is not usually necessary, as user agents
+    will generally take care of updating <span title="application
+    cache">application caches</span> automatically.</p>
+
+    <p>The method can be useful in situations such as long-lived
+    applications. For example, a Web mail application might stay open
+    in a browser tab for weeks at a time. Such an application could
+    want to test for updates each day.</p>
+
    </dd>
 
    <dt><var title="">cache</var> . <code title="dom-appcache-abort">abort</code>()</dt>
    <dd>
 
     <p>Cancels the <span>application cache download process</span>.</p>
 
+    <p>This method is intended to be used by Web application showing
+    their own caching progress UI, in case the user wants to stop the
+    update (e.g. because bandwidth is limited).</p>
+
    </dd>
 
    <dt><var title="">cache</var> . <code title="dom-appcache-swapCache">swapCache</code>()</dt>
@@ -76862,6 +76875,19 @@ NETWORK:
     that subsequent requests for cached resources will obtain the
     newer copies.</p>
 
+    <p>The <code title="event-appcache-updateready">updateready</code>
+    event will fire before this method can be called. Once it fires,
+    the Web application can, at its leisure, call this method to
+    switch the underlying cache to the one with the more recent
+    updates. To make proper use of this, applications have to be able
+    to bring the new features into play; for example, reloading
+    scripts to enable new features.</p>
+
+    <p>An easier alternative to <code
+    title="dom-appcache-swapCache">swapCache()</code> is just to
+    reload the entire page at a time suitable for the user, using
+    <code title="dom-location-reload">location.reload()</code>.</p>
+
    </dd>
 
   </dl>