Improve path.resolve documentation

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
+If `to` isn't already absolute `from` arguments are prepended in right to left
-point from where the path will be resolved. `resolve` will prepend `from`
+order, until an absolute path is found. If after using all `from` paths still
-arguments from right to left until an absolute path is found. If no `from`
+no absolute path is found, the current working directory is used as well. The
-arguments are specified, or after prepending them still no absolute path is
+resulting path is normalized, and trailing slashes are removed unless the path 
-found, the current working directory will be prepended eventually.
+gets resolved to the root directory.
 
-Trailing slashes are removed unless the path gets resolved to the root
+Another way to think of it is as a sequence of `cd` commands in a shell.
-directory.
 
-Examples:
+    path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
 
-    path.resolve('index.html')
+Is similar to:
-    // returns
+
-    '/home/tank/index.html'
+    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
+    // if currently in /home/myself/node, it returns
-    '/home/tank/wwwroot/static_files/gif/image.gif'
+    '/home/myself/node/wwwroot/static_files/gif/image.gif'
 
 ### path.dirname(p)