doc,test: empty strings in path module

The path module's `join, normalize, isAbsolute, relative and resolve`
functions return/use the current directory if they are passed zero
length strings.

    > process.version
    'v2.3.4-pre'
    > path.win32.join('')
    '.'
    > path.posix.join('')
    '.'
    > path.win32.normalize('')
    '.'
    > path.posix.normalize('')
    '.'
    > path.win32.isAbsolute('')
    false
    > path.posix.isAbsolute('')
    false
    > path.win32.relative('', '')
    ''
    > path.posix.relative('', '')
    ''
    > path.win32relative('.', '')
    ''
    > path.posix.relative('.', '')
    ''
    > path.posix.resolve('')
    '/home/thefourtheye/Desktop'
    > path.win32.resolve('')
    '\\home\\thefourtheye\\Desktop'

Since empty paths are not valid in any of the operating systems people
normally use, this behaviour might be a surprise to the users. This
commit introduces "Notes" about this, wherever applicable in `path`'s
documentation.

The tests makes sure that the behaviour is intact between
commits.

PR-URL: https://github.com/nodejs/io.js/pull/2106
Reviewed-By: Rich Trott <rtrott@gmail.com>

1 files changed, 20 insertions, 1 deletions

diff --git a/doc/api/path.markdown b/doc/api/path.markdown
index 08495a79e5..7177ab4d2d 100644
--- a/doc/api/path.markdown
+++ b/doc/api/path.markdown
@@ -22,6 +22,9 @@ Example:
     // returns
     '/foo/bar/baz/asdf'
 
+*Note:* If the path string passed as argument is a zero-length string then `'.'`
+        will be returned, which represents the current working directory.
+
 ## path.join([path1][, path2][, ...])
 
 Join all arguments together and normalize the resulting path.
@@ -39,6 +42,11 @@ Example:
     // throws exception
     TypeError: Arguments to path.join must be strings
 
+*Note:* If the arguments to `join` have zero-length strings, unlike other path
+        module functions, they will be ignored. If the joined path string is a
+        zero-length string then `'.'` will be returned, which represents the
+        current working directory.
+
 ## path.resolve([from ...], to)
 
 Resolves `to` to an absolute path.
@@ -78,6 +86,9 @@ Examples:
     // if currently in /home/myself/iojs, it returns
     '/home/myself/iojs/wwwroot/static_files/gif/image.gif'
 
+*Note:* If the arguments to `resolve` have zero-length strings then the current
+        working directory will be used instead of them.
+
 ## path.isAbsolute(path)
 
 Determines whether `path` is an absolute path. An absolute path will always
@@ -94,9 +105,13 @@ Windows examples:
 
     path.isAbsolute('//server')  // true
     path.isAbsolute('C:/foo/..') // true
-    path.isAbsolute('bar\\baz')   // false
+    path.isAbsolute('bar\\baz')  // false
     path.isAbsolute('.')         // false
 
+*Note:* If the path string passed as parameter is a zero-length string, unlike
+        other path module functions, it will be used as-is and `false` will be
+        returned.
+
 ## path.relative(from, to)
 
 Solve the relative path from `from` to `to`.
@@ -117,6 +132,10 @@ Examples:
     // returns
     '../../impl/bbb'
 
+*Note:* If the arguments to `relative` have zero-length strings then the current
+        working directory will be used instead of the zero-length strings. If
+        both the paths are the same then a zero-length string will be returned.
+
 ## path.dirname(p)
 
 Return the directory name of a path.  Similar to the Unix `dirname` command.