search

brackets-archive / bracketsIssues

Archive of issues in brackets.
0 stars 0 forks source link

[CLOSED] NativeFileSystem isn't well-documented #1046

Open core-ai-bot opened 3 years ago

core-ai-bot commented 3 years ago

Issue by njx Thursday Jun 14, 2012 at 22:03 GMT Originally opened as https://github.com/adobe/brackets/issues/1052

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.

core-ai-bot commented 3 years ago

Comment by pthiess Tuesday Jun 19, 2012 at 17:47 GMT

Reviewed -@tvoliter

core-ai-bot commented 3 years ago

Comment by pthiess Wednesday Sep 05, 2012 at 16:42 GMT

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

core-ai-bot commented 3 years ago

Comment by jasonsanjose Thursday Dec 13, 2012 at 18:01 GMT

Marking fix in progress by@jbalsas

core-ai-bot commented 3 years ago

Comment by jbalsas Friday Mar 29, 2013 at 17:59 GMT

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

core-ai-bot commented 3 years ago

Comment by njx Friday Mar 29, 2013 at 18:06 GMT

@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 :))

core-ai-bot commented 3 years ago

Comment by jbalsas Friday Mar 29, 2013 at 18:18 GMT

@njx I'd say that was addressed back in https://github.com/adobe/brackets/pull/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?

core-ai-bot commented 3 years ago

Comment by njx Friday Mar 29, 2013 at 18:20 GMT

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!