NativeFileSystem isn't well-documented

[njx]

It's a little hard to know how you're supposed to use NativeFileSystem without going and reading a bunch of W3C docs, and we also don't have documentation for our custom entry point (requestNativeFileSystem()). We should at least have an introductory comment at the top of the file showing basic usage, and pointing to the relevant specs. Also need to fill out the jsdoc comments for most of the API functions.

[pthiess]

Reviewed - @tvoliter

[pthiess]

Reassigning to @njx - NJ, please delegate as needed.
THX, Peter.

[jasonsanjose]

Marking fix in progress by @jbalsas

[jbalsas]

@njx Just realized this is still open... time to close it? ;)

[njx]

@jbalsas Ah, I totally missed that pull request :) Looks good! The only thing that might be worth adding is how to actually get a DirectoryEntry or FileEntry. I think the "correct" way to do it according to the HTML5 docs is to always start with requestFileSystem().root and then walk down to the appropriate file/directory, but we often just do new FileEntry(). I wonder if we should explicitly mention that in the comments (or whether we should stop doing that and discourage it :))

[jbalsas]

@njx I'd say that was addressed back in #2158 with the implementation of the FileSystem interface. Now, our own requestNativeFileSystem and resolveFileSystemPath both return filesystems with root as described in the specs. Was that what you meant?

Of course, we could add one more general example, or make it more explicit in those methods' docs... what do you think?

[njx]

Ah. I guess I was just wondering if we should assume that everyone should use that correct interface, or whether it was okay to suggest to people that they do what we do in other places (newing up entries directly). I guess that's really a separate issue.

I'll close this one and open a code cleanup bug for that issue. Thanks!