Documenting the lack of Windows support for fs.watchFile

[TrevorBurnham]

fs.watchFile doesn't exist under Windows (#1358), yet the docs don't mention this. If fs.watch is the future, the docs should push Node devs to use it.

[piscisaureus]

@TrevorBurnham The issue is that fs.watch() is not rock solid yet. We don't really want to push people onto it just yet. Instead we should add fs.watchFile support to windows.

[TrevorBurnham]

@piscisaureus Ah, thanks for the clarification. Could you elaborate further? Over at the CoffeeScript project, we've been trying all day to figure out how to handle fs.watch vs. fs.watchFile. There's very mixed information out there; over at #1358, @bnoordhuis said

fs.watchFile() will be gone before 0.6.0, it's superseded by fs.watch().

The same claim was also in the API changes list on the wiki, until I removed it earlier today (on the basis that fs.watchFile still works on non-Windows sytems and is in the documentation).

Meanwhile, fs.watch has serious bugs, at least on the Mac (#1986). So where is Node headed, with respect to file-watching? Will fs.watchFile support be added to Windows? Or to the contrary, will fs.watchFile be removed?

[TrevorBurnham]

@piscisaureus Your objection is just to the wording, right? How about simply

***Warning:*** This method is not supported under Windows, and will throw an exception.

Unless a Windows implementation of watchFile is coming soon, I feel like this really ought to be documented.

[Nodejs-Jenkins]

Can one of the admins verify this patch?

[tjfontaine]

This isn't valid anymore, the documentations mentions the caveats surrounding Node and file watching. Thanks!