From 63874dadf6a5c093cfe00829acdc7a6a56850f29 Mon Sep 17 00:00:00 2001
From: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Date: Sun, 5 Jul 2015 15:08:16 +0000
Subject: [PATCH] doc: Adding note about 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.join('')
    '.'
    > 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.
---
 doc/api/path.markdown | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/doc/api/path.markdown b/doc/api/path.markdown
index 08495a79e5399c..93dce0d5fe06e9 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 is a zero-length string then the current working directory
+        will be returned.
+
 ## path.join([path1][, path2][, ...])
 
 Join all arguments together and normalize the resulting path.
@@ -39,6 +42,9 @@ Example:
     // throws exception
     TypeError: Arguments to path.join must be strings
 
+*Note:* If the joined path is a zero-length string then the current working
+        directory will be returned.
+
 ## path.resolve([from ...], to)
 
 Resolves `to` to an absolute path.
@@ -78,6 +84,9 @@ Examples:
     // if currently in /home/myself/iojs, it returns
     '/home/myself/iojs/wwwroot/static_files/gif/image.gif'
 
+*Note:* If the path is a zero-length string then the current working directory
+        will be used.
+
 ## path.isAbsolute(path)
 
 Determines whether `path` is an absolute path. An absolute path will always
@@ -94,9 +103,11 @@ 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 is a zero-length string then `false` will be returned.
+
 ## path.relative(from, to)
 
 Solve the relative path from `from` to `to`.
@@ -117,6 +128,10 @@ Examples:
     // returns
     '../../impl/bbb'
 
+*Note:* If any of the paths passed are zero-length strings then the current
+        working directory will be used instead. 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.