NativeFileSystem documentation and examples (#1052)

[jbalsas]

Hi,

I was going through NativeFileSystem the other day and ran across #1052

This pull request should address those concerns. Additionally, it removes some unused requires with NativeFileSystem.

As pointed out in #2058, some of the APIs are not consitent with the current specs. The jsdocs here reflect the specs, and would need to get updated with that information.

[jasonsanjose]

Assigned to me. @jbalsas Now that the other NativeFileSystem changes are merged, do you want to update this pull request or should I close this?

[jbalsas]

Sure! Let me merge with master first and then review and update this before you take a look.

[jbalsas]

@jasonsanjose Merged and updated. All yours ;)

[jasonsanjose]

I think resolveNativeFileSystemPath is a more appropriate example. Thoughts?

[jbalsas]

Yes, makes sense. This wasn't implemented by the time I added the examples, though. Will switch to resolveNativeFileSystemPath here.

[jasonsanjose]

Remove !

[jasonsanjose]

Initial review complete. Thanks for taking this one.

[jbalsas]

@jasonsanjose I'll dive into this later today. Just need one clarification.

From the Closure Compiler docs, ! stands for Non-nullable type which Indicates that a value is type A and not null. This aligns with the w3c specs where the error callbacks are defined as optional, non-nullable functions.

Is it possible that we're using ! throughout the docs to mark required arguments instead of non-nullable? If so... should we stick to that?

Furthermore, if we stick to the meaning of ! in the Closure Compiler, Functions and all value types (boolean, number, and string) are non-nullable by default so we could even remove all instances of ! found along functions.

What do you think?

[jasonsanjose]

Yep, we're using ! wrong. I'll file a separate bug to resolve that.

You're right that it seems redundant to add ! when they are non-nullable by default. I think it's ok to remove ! in that case.

[jbalsas]

I think I've addressed all your comments. Ready for a second pass.

[jasonsanjose]

Looks great. I filed #2360 to cover the incorrect annotations. Merging.