diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown
index c263380d674..96bef91eb56 100644
--- a/doc/api/fs.markdown
+++ b/doc/api/fs.markdown
@@ -194,12 +194,22 @@ linkString)`.
 
 Synchronous readlink(2). Returns the symbolic link's string value.
 
-## fs.realpath(path, [callback])
+## fs.realpath(path, [cache], callback)
 
-Asynchronous realpath(2).  The callback gets two arguments `(err,
-resolvedPath)`.  May use `process.cwd` to resolve relative paths.
+Asynchronous realpath(2). The `callback` gets two arguments `(err,
+resolvedPath)`. May use `process.cwd` to resolve relative paths. `cache` is an
+object literal of mapped paths that can be used to force a specific path
+resolution or avoid additional `fs.stat` calls for known real paths.
 
-## fs.realpathSync(path)
+Example:
+
+    var cache = {'/etc':'/private/etc'};
+    fs.realpath('/etc/passwd', cache, function (err, resolvedPath) {
+      if (err) throw err;
+      console.log(resolvedPath);
+    });
+
+## fs.realpathSync(path, [cache])
 
 Synchronous realpath(2). Returns the resolved path.