doc: stability index 2 = stable in fs.markdown, fixes #1754

[Trott]

Addresses #1754

[brendanashworth]

I think this line can be removed altogether - APIs are by default stable.

[silverwind]

Also make sure the commit title (and probably the PR title) and message follows the guideline here: https://github.com/nodejs/io.js/blob/v1.x/CONTRIBUTING.md#step-3-commit.

[Trott]

Amended my previous commit and changed the name of this commit per @silverwind.

Added a commit to remove redundant stability index indication per @brendanashworth. (Are the other two redundant as well? There's a stability index indication at the top that would seemingly apply to everything.)

[brendanashworth]

perhaps @bnoordhuis could share some wisdom on that? my intuition says we move the recommendation into the text, out of the stability note (and remove that).

[Fishrock123]

I'd move to remove per-function stability index across the docs. Is this the only spot?

[brendanashworth]

@Fishrock123 yes, besides deprecation notices, fs is the only culprit.

[Trott]

domain.markdown is a curious case. The entire API is stability index 0 (deprecated), but there's an additional inline stability index 0 notice on domain.dispose().

[Trott]

Back to fs.watch vs fs.watchFile... I wonder if it would be useful to provide a single sentence explaining why fs.watch is preferred. Maybe summarize http://tech.nitoyon.com/en/blog/2013/10/02/node-watch-impl/ in a sentence or two.

[brendanashworth]

@Trott that sounds like a good plan.

[ChALkeR]

@brendanashworth What about patching fs.watchFile instead so it first tries to use the native fs notify api (as fs.watch does now) and if it fails, fallback to the current polling (as fs.watchFile does now)? I can open a separate issue for that.
Edit: btw, see https://github.com/paulmillr/chokidar

[Trott]

I pushed a new commit to make the changes described. I think (except for stuff that should go in separate tickets) I'm all caught up with the comments.

[Fishrock123]

It'd be slightly better if this was a little more in line with how 86dd244 was. You can apply the patch below if you'd like, otherwise I'll just land this with it.

diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown
index 176a0e9..92f34db 100644
--- a/doc/api/fs.markdown
+++ b/doc/api/fs.markdown
@@ -556,9 +556,9 @@ These stat objects are instances of `fs.Stat`.
 If you want to be notified when the file was modified, not just accessed
 you need to compare `curr.mtime` and `prev.mtime`.

-`fs.watch` is more efficient than `fs.watchFile` and `fs.unwatchFile`.
+_Note: `fs.watch` is more efficient than `fs.watchFile` and `fs.unwatchFile`.
 `fs.watch` should be used instead of `fs.watchFile` and `fs.unwatchFile`
-when possible.
+when possible._

 ## fs.unwatchFile(filename[, listener])

@@ -569,9 +569,9 @@ have effectively stopped watching `filename`.
 Calling `fs.unwatchFile()` with a filename that is not being watched is a
 no-op, not an error.

-`fs.watch` is more efficient than `fs.watchFile` and `fs.unwatchFile`.
+_Note: `fs.watch` is more efficient than `fs.watchFile` and `fs.unwatchFile`.
 `fs.watch` should be used instead of `fs.watchFile` and `fs.unwatchFile`
-when possible.
+when possible._

 ## fs.watch(filename[, options][, listener])

[brendanashworth]

@ChALkeR the behavior would probably change for fs.watchFile, and it'd break backwards compatibility. It is probably best to note it in the docs and let it sit for a while.

[Fishrock123]

@ChALkeR We aren't actually deprecating it.

[ChALkeR]

@Fishrock123 I never said anything about deprecating here.

@brendanashworth How would that break backwards compatibility? Do the modules rely on how is fs.watchFile implemented internally? I propose to keep the API but to switch it internally to more efficient way of watching a file when it is possible, and when it's not — fallback to the current polling implementation. Even interval could be faked (by delaying the notification) to keep the API completely compatible.

[Trott]

Agree with @Fishrock123 on styling to set the note off from the main text a bit. Added a new commit for it.

[Fishrock123]

Thanks, landed in eb1856d