[DataCache] General Comments and Correction for the New WD

Some driveby comments. There were a lot of changes, but these were
just what I caught with a quick scan.  I can see you've put a lot
of work into this, Thanks!


---- General ----

- 4.1 Introduction
  http://dev.w3.org/2006/webapi/DataCache/#datacache-intro
  
  review policy says "(only for unsafe HTTP methods)".
  
  Why discriminate? I could see an application wanting to review a GET
  request. For example, an application which can be updated by multiple
  clients. It may be useful to examine the data returned from a GET,
  which may contain information data that the other clients POST/PUT.


- IDL Descriptions
  HttpRequest#bodyText and HttpResponse#bodyText
  http://dev.w3.org/2006/webapi/DataCache/#widl-HttpRequest-bodyText
  http://dev.w3.org/2006/webapi/DataCache/#widl-HttpResponse-bodyText
  
  The description of the DOMString is currently:
  
    [[
      This attribute, on getting, must return the entity body of this
      HttpRequest object, if the body has a Content-Type of either
      text/* or application/xml.
    ]]
  
  I think this is rather restrictive. For one, JSON data transferred
  with the Content-Type "application/json" would be just as useful (if
  not more so) as XML. For that matter, XML can be transferred with
  different types. Take AtomPub for example, it uses
  "application/atom+xml".
  
  Is there a generalization that can be applied here? A white-list is
  likely  overly restrictive, and not future proof.


- Usefulness of incrementPendingUpdates / decrement
  http://dev.w3.org/2006/webapi/DataCache/#widl-CacheTransactionRequest-incrementPendingUpdates

  Is the number of updates useful, or even accessible? It seems as
  though developers only really need to know if there are any updates
  or not. A "dirty" flag boolean for instance.



---- Events ----

4.2.1 Starting a transaction
http://dev.w3.org/2006/webapi/DataCache/#starting-a-transaction
updating event is a dead hyperlink. Did this get dropped?


4.2.4 Committing a transaction
http://dev.w3.org/2006/webapi/DataCache/#complete-transaction
updateready event is not mentioned elsewhere. Do you mean the "ready" event?


4.2.5 Aborting a transaction
http://dev.w3.org/2006/webapi/DataCache/#abort-transaction
error event is not mentioned elsewhere. Did this get dropped?

I also noticed that a lot of the Events now trigger with the Event
interface, and not the CacheEvent interface. Overall, I think the
Event's have had the most changes in the last few revisions, and
need to be cleaned up everywhere.



---- Typos ----

4.2.7 Asynchronous reuests
http://dev.w3.org/2006/webapi/DataCache/#request-events
As you can see, it should be "Asynchronous requests" in both the Table
of Contents and the section's header.



---- Other ----

Table of Contents
"4.2.8 Extending the ApplicationCache interface" is a link, but its
href is just "#" as that section does not have an id.

Received on Friday, 1 January 2010 21:39:32 UTC