From 01148265cbf27548cf4a55024e2677119e237d2d Mon Sep 17 00:00:00 2001
From: Bert Belder <bertbelder@gmail.com>
Date: Tue, 11 Jan 2011 02:57:25 +0100
Subject: [PATCH] Improve path.resolve documentation

---
 doc/api/path.markdown | 38 +++++++++++++++++++++++---------------
 1 file changed, 23 insertions(+), 15 deletions(-)

diff --git a/doc/api/path.markdown b/doc/api/path.markdown
index 5f6555464fe..36544f6c17b 100644
--- a/doc/api/path.markdown
+++ b/doc/api/path.markdown
@@ -29,34 +29,42 @@ Example:
 
 ### path.resolve([from ...], to)
 
-Resolves `to` to an absolute path name and normalizes it.
+Resolves `to` to an absolute path.
 
-One ore more `from` arguments may be provided to specify the the starting
-point from where the path will be resolved. `resolve` will prepend `from`
-arguments from right to left until an absolute path is found. If no `from`
-arguments are specified, or after prepending them still no absolute path is
-found, the current working directory will be prepended eventually.
+If `to` isn't already absolute `from` arguments are prepended in right to left
+order, until an absolute path is found. If after using all `from` paths still
+no absolute path is found, the current working directory is used as well. The
+resulting path is normalized, and trailing slashes are removed unless the path 
+gets resolved to the root directory.
 
-Trailing slashes are removed unless the path gets resolved to the root
-directory.
+Another way to think of it is as a sequence of `cd` commands in a shell.
 
-Examples:
+    path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
 
-    path.resolve('index.html')
-    // returns
-    '/home/tank/index.html'
+Is similar to:
+
+    cd foo/bar
+    cd /tmp/file/
+    cd ..
+    cd a/../subfile
+    pwd
+
+The difference is that the different paths don't need to exist and may also be
+files.
+
+Examples:
 
     path.resolve('/foo/bar', './baz')
     // returns
-    '/foo/baz/baz'
+    '/foo/bar/baz'
 
     path.resolve('/foo/bar', '/tmp/file/')
     // returns
     '/tmp/file'
 
     path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')
-    // returns
-    '/home/tank/wwwroot/static_files/gif/image.gif'
+    // if currently in /home/myself/node, it returns
+    '/home/myself/node/wwwroot/static_files/gif/image.gif'
 
 ### path.dirname(p)