- From: timeless <timeless@gmail.com>
- Date: Sun, 14 Jun 2009 18:28:13 +0300
- To: Arun Ranganathan <arun@mozilla.com>, public-webapps <public-webapps@w3.org>
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 Sunday, 14 June 2009 15:28:50 UTC