Re: File API - W3C Working Draft 7 June 2009

Timeless,

These are all sensible nits and I'll incorporate them.

-- A*

timeless wrote:
> http://dev.w3.org/2006/webapi/FileUpload/publish/FileAPI.xhtml
>
> Note, I expect all of my comments here to be of an editorial nature.
>
> In the Abstract:
>   
>> use of appropriate [DOM]DOM methods should return a FileList object,
>>     
>
> [DOM]DOM has no markup and seems very out of place.
>
>   
>> have the ability to manipulate as wide as possible a range of user input,
>>     
>
> this is awkward (yes, I should suggest a fix, sorry, not today).
>
>   
>> programmatic ways to prompt file selection
>>     
>
> prompt _for_ ?
>
>   
>> This interface exposes the list of files that has been selected.
>>     
>
> _have_ been
>
>   
>> When no file has been selected, the length attribute is zero.
>>     
>
> If no files are selected, ....
>
> ---
>   interface FileList {
>   readonly attribute unsigned long  length;
> ---
>
> You have two spaces before 'length', i'm not quite sure why,
> File.fileSize doesn't get this treatment :)
>
>   
>> Index into the collection.  Valid values are from 0 to length-1
>>     
>
> do you want a period here?
>
>   
>> and never need to hold more than a few of its bytes in memory
>>     
>
> ... need never hold ...
>
>   
>> Therefore the content of the file may change or cease to be available between the moment the file is selected and the moment it is accessed.
>>     
>
> While I understand that you're trying to explain this, this isn't a
> good way to do so, and doesn't clearly explain the problems about
> which you're trying to warn.
>
>   
>> implementations SHOULD asynchronously use
>> a FileError object parameter with an errorCode when invoking
>> the FileErrorCallback callback .
>>     
>
> Does this mean that FileAsText will be called before FileErrorCallback?
>
>   
>>       // I can haz xhr.send(fileAsDataURI);
>>     
>
> I believe future generations would appreciate standard English.
> Personally, I'd appreciate more consistent indentation/styling wrt. space
>
>   
>> Asynchronously provides access to the File object's data as string.
>>     
>
> as _a_ string
>
>   
>>  Additionally, an optional error callback can be provided by the caller, to determine
>> whether there is a FileError, and handle it.
>>     
>
> This is confusing. "Determine" doesn't really fit. And personally, I'd
> rather a single function with two arguments. I'm always going to be
> called, often with null, you might as well just give me an error
> object at the same time (and feel free to be lazy about populating
> it).
>
>   
>> See accept
>> .
>>     
>
> Please arrange for the period to be on the same line as the rest :)
>
>   
>> callback of type FileListDataCallback
>>     
>
> I don't understand what happens if the caller asks for multiple and
> the user only provides one.
>
>   
>> This callback handles the files picked by the user, and is called with a FileList
>> parameter.  If the multiple parameter is used with the open method, this callback is
>> invoked with a FileList with a length greater than 1.
>>     
>
> The sample you've defined shows an instant problem, total lack of file
> identity. In order to do anything useful, someone would have to retain
> file state independently, which is likely to be painful.
>
>   
>> The accept  attribute may be specified to provide user agents
>> with a hint of what file types the server will be able to accept.
>>     
>
> As this is for a Client side API, it'd be best to avoid mention of
> "server" and instead favor "web application".
>
>   
>> If this optional parameter is used to invoke the open method,
>> it must consist of a set of comma-separated tokens,
>> each of which must be an ASCII case-insensitive match for one of the following:
>>     
>
> So I can't specify "*/*"? :)
>
>   
>>  IF the
>> user interaction layer raised by implementations
>> has been dismissed without granting permission.
>>     
>
> Is the capital "F" really necessary? :)
>
>   
>> Methods in this specification may throw an error, which are reported
>>     
>
> an error is singular, "are" is not.
>
>   
>> The file that is trying to be read does not exist.
>>     
>
> files are inanimate objects, they don't try to do anything :)
>
>   
>> This may be due to it having been moved or deleted after a pointer to it was
>>     
>
> please request "pointer" with "reference" :)
>
>   
>> acquired (e.g. concurrent modification with another application).
>>     
>
>   
>> This error code has been previously defined in DOMException [DOMCORE].
>>     
>
>   
>> The file cannot be read. This may be due to permission problems that occur
>> after a File object has been obtained (e.g. concurrent lock with another application).
>>     
>
> you used "acquired" earlier, I like "obtained" better, please be consistent.
>

Received on Thursday, 18 June 2009 20:20:43 UTC