- From: Ms2ger <ms2ger@gmail.com>
- Date: Fri, 10 Feb 2012 21:27:27 +0100
- To: Arun Ranganathan <arun@mozilla.com>
- CC: "public-webapps@w3.org" <public-webapps@w3.org>
Hi Arun, I've read the File API specification, and have a number of comments: == 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. This paragraph is inconsistent about linking File and Blob to their definitions. The example has > if(evt.target.error.name == "NOT_READABLE_ERR") { which probably should be "NotReadableError". == 2. Conformance == I think it's surprising that notes are normative, unlike (AFAICT) most other Web API specifications. == 4. Terminology and Algorithms == The >= and <= operators don't seem to be used in the specification. == 6. The Blob Interface == The constructor can use the new WebIDL unions types, as > Constructor((ArrayBuffer or Blob or DOMString)[] blobParts, > optional BlobPropertyBag options) === 6.1. Constructors === The reference to ES5 doesn't seem necessary. === 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". === 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. == 7. The File Interface == Something's weird with the indentation in the IDL block here. > readonly attribute Date lastModifiedDate; should be "Date?", as it can return null. == 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". === 8.5. Reading a File or Blob === The result attribute should probably be declared as | readonly attribute (DOMString or ArrayBuffer)? result; ==== 8.5.7. Blob Parameters ==== I have no idea what this section is actually supposed to define. ===== 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. ===== 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. == 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 . Or? 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. == 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. === 11.2. Discussion of Existing Schemes === > Choosing a name that clarifies the primary use case -- namely, access > to memory-resident Blob resources -- is a worthwhile compromise, and > favors clarity, familiarity, and consistency across the web platform. En dashes again. === 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. === 11.6. Lifetime of Blob URIs === Should reference the oneTimeOnly argument here. === 11.8. Creating and Revoking a Blob URI === // Window implements URL; // WorkerUtils implements URL; Those statements are out of place, and don't mean what they seem to. Instead, they would require createObjectURL and revokeObjectURL to exist on the Window and WorkerUtils interfaces. === 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. > In the example below, two Image elements Should say "|img| elements" for consistency. == 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. HTH Ms2ger [1] http://ln.hixie.ch/?start=1140242962&count=1
Received on Friday, 10 February 2012 20:27:59 UTC