[FileAPI] Various comments

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