doc: document fs.watchFile behaviour on ENOENT

When fs.watchFile encounters an ENOENT error, it invokes the given
callback with some error data. This caused an issue as it was different
behaviour than Node v0.10. Instead of changing this behaviour, document
it and add a test.

Ref: #1745
Ref: #2028
Reviewed-By: Ben Noordhuis <[email protected]>
PR-URL: #2093

doc/api/fs.markdown

@@ -576,6 +576,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`.
 
+_Note: when an `fs.watchFile` operation results in an `ENOENT` error, it will
+invoke the callback once. This is a change in functionality since v0.10._
+
 _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._

test/parallel/test-fs-watchfile.js

@@ -1,7 +1,10 @@
 'use strict';
 
 const fs = require('fs');
+const path = require('path');
 const assert = require('assert');
+const common = require('../common');
+const fixtures = path.join(__dirname, '..', 'fixtures');
 
 // Basic usage tests.
 assert.throws(function() {
@@ -15,3 +18,9 @@ assert.throws(function() {
 assert.throws(function() {
   fs.watchFile(new Object(), function() {});
 }, /Path must be a string/);
+
+// Test ENOENT. Should fire once.
+const enoentFile = path.join(fixtures, 'empty', 'non-existent-file');
+fs.watchFile(enoentFile, common.mustCall(function(curr, prev) {
+  fs.unwatchFile(enoentFile);
+}));