- From: Arun Ranganathan <aranganathan@mozilla.com>
- Date: Sat, 18 Feb 2012 14:20:39 -0800 (PST)
- To: Ms2ger <ms2ger@gmail.com>
- Cc: public-webapps@w3.org
Ms2ger,
Many thanks for the detailed review.
>
> == 1. Introduction ==
>
> > "Binary Large Object" -- a name originally introduced to web APIs
> > in Google Gears
>
> should use an en dash (—, U+2013) instead of two hyphens.
Done.
>
> This paragraph is inconsistent about linking File and Blob to their
> definitions.
Done.
> The example has
>
> > if(evt.target.error.name == "NOT_READABLE_ERR") {
>
> which probably should be "NotReadableError".
Done.
>
> == 2. Conformance ==
>
> I think it's surprising that notes are normative, unlike (AFAICT)
> most
> other Web API specifications.
Upon reflection, I have used "notes" rather liberally. I've removed all normative notes making them just a part of the specification.
> == 4. Terminology and Algorithms ==
>
> The >= and <= operators don't seem to be used in the specification.
Eliminated reference to them.
>
> == 6. The Blob Interface ==
>
> The constructor can use the new WebIDL unions types, as
>
> > Constructor((ArrayBuffer or Blob or DOMString)[] blobParts,
> > optional BlobPropertyBag options)
>
Done. Presumably WebIDL also handles what happens when a contructor is invoked with an argument not in the union type, so I don't need to say what happens in that case.
> === 6.1. Constructors ===
>
> The reference to ES5 doesn't seem necessary.
>
Done.
> === 6.2. Attributes ===
>
> > On getting, conforming user agents SHOULD return the MIME type of
> > the Blob, if it is known.
>
> Should be MUST, as we already have "if it is known".
Done.
>
> === 6.3. Methods and Parameters ===
>
> The contentType normalization should not special-case undefined; if
> an
> author passes undefined, it should be treated as "undefined" per
> WebIDL.
Done.
>
> == 7. The File Interface ==
>
> Something's weird with the indentation in the IDL block here.
Fixed.
>
> > readonly attribute Date lastModifiedDate;
>
> should be "Date?", as it can return null.
Done.
>
> == 8. The FileReader Interface ==
> === 8.1. The FileReader Task Source ===
>
> > The FileReader interface enables asynchronous reads on individual
> > Blob objects by firing progress events as the read occurs to event
> > handler methods on the FileReader, which is an EventTarget
> > [DOMCore].
>
> This seems to suggest that one can only use the event handler methods
> (attributes?), but not add/removeEventListener. Maybe just remove to
> "event handler methods".
Done.
>
> === 8.5. Reading a File or Blob ===
>
> The result attribute should probably be declared as
>
> | readonly attribute (DOMString or ArrayBuffer)? result;
Done.
>
> ==== 8.5.7. Blob Parameters ====
>
> I have no idea what this section is actually supposed to define.
Clarified.
>
> ===== 8.5.9.1. Event Summary =====
>
> > … the table below is normative for the events in this
> > specification.
>
> The table should not be normative; the events are already fired in
> the
> respective algorithms.
Done.
>
> ===== 8.5.9.2. Summary of Event Invariants =====
>
> > The following are normative invariants …
>
> What are "normative invariants"? This seems to be a list of
> statements
> of fact [1], and as such should be informative.
Done.
>
> == 10. Errors and Exceptions ==
> === 10.1. Throwing an Exception or Returning an Error ===
>
> > Synchronous read methods throw exceptions of the type in the table
> > below if there has been an error with reading or .
Fixed.
>
>
> The EncodingError cell seems to confusingly use "encoding" for a
> concept
> related to the length of a data URL and character encodings; I don't
> see
> how these concepts are related.
>
The problem is in Base64-encoding "long" files subject to URL-length limitations. I've clarified this.
> == 11. A URI for Blob and File reference ==
> === 11.1. Requirements for a New Scheme ===
>
> This section uses |img| and <img> inconsistently, it should use the
> former.
Done.
>
> === 11.2. Discussion of Existing Schemes ===
>
> > Choosing a name that ....
>
> En dashes again.
Done :)
>
> === 11.3. Definition of blob URI Scheme ===
>
> > Opaque strings MUST NOT include any reserved characters from
> > [RFC3986] without percent-encoding them; these characters MUST be
> > percent-encoded.
>
> Redundant requirements.
Clarified.
>
> === 11.6. Lifetime of Blob URIs ===
>
> Should reference the oneTimeOnly argument here.
Done (great suggestion).
>
> === 11.8. Creating and Revoking a Blob URI ===
>
> // Window implements URL;
> // WorkerUtils implements URL;
Eliminated.
>
> === 11.9. Examples of Blob URI Creation and Revocation ===
>
> > Blob URIs are strings that dereference Blob objects, and can
> > persist
> > for as long as the document from which they were minted using
> > URL.createObjectURL() -- see _Lifetime of Blob URIs_.
>
> En dash, and the "Lifetime of Blob URIs" link is broken.
Fixed.
>
> > In the example below, two Image elements
>
> Should say "|img| elements" for consistency.
Fixed.
>
> == 16. References ==
>
> Aryeh Gregor is now also editing DOM Core, which has been renamed to
> DOM4.
>
> The URL specification is now at
> <http://dvcs.w3.org/hg/url/raw-file/tip/Overview.html>.
>
> The "Stream API" reference has a broken link.
Duly noted and fixed.
This review has been invaluable -- thank you!
-- A*
Received on Saturday, 18 February 2012 22:21:07 UTC