doc: general improvements to path.md copy

PR-URL: https://github.com/nodejs/node/pull/7122
Reviewed-By: Brian White <mscdex@mscdex.net>

1 files changed, 243 insertions, 126 deletions

diff --git a/doc/api/path.md b/doc/api/path.md
index 3cbab43c6c..f18ed52730 100644
--- a/doc/api/path.md
+++ b/doc/api/path.md
@@ -2,37 +2,93 @@
 
     Stability: 2 - Stable
 
-This module contains utilities for handling and transforming file
-paths. The file system is not consulted to check whether paths are valid.
+The `path` module provides utilities for working with file and directory paths.
+It can be accessed using:
 
-Use `require('path')` to use this module.  The following methods are provided:
+```js
+const path = require('path');
+```
+
+## Windows vs. POSIX
+
+The default operation of the `path` module varies based on the operating system
+on which a Node.js application is running. Specifically, when running on a
+Windows operating system, the `path` module will assume that Windows-style
+paths are being used.
+
+For example, using the `path.basename()` function with the Windows file path
+`C:\temp\myfile.html`, will yield different results when running on POSIX than
+when run on Windows:
+
+On POSIX:
+
+```js
+path.basename('C:\\temp\\myfile.html');
+  // returns 'C:\temp\myfile.html'
+```
+
+On Windows:
+
+```js
+path.basename('C:\\temp\\myfile.html');
+  // returns 'myfile.html'
+```
+
+To achieve consistent results when working with Windows file paths on any
+operating system, use [`path.win32`][]:
+
+On POSIX and Windows:
+
+```js
+path.win32.basename('C:\\temp\\myfile.html');
+  // returns 'myfile.html'
+```
+
+To achieve consistent results when working with POSIX file paths on any
+operating system, use [`path.posix`][]:
+
+On POSIX and Windows:
+
+```js
+path.posix.basename('/tmp/myfile.html');
+  // returns 'myfile.html'
+```
 
 ## path.basename(path[, ext])
 <!-- YAML
 added: v0.1.25
 -->
 
-Return the last portion of a path, similar to the Unix `basename` command.
-`path` must be a string. `ext`, if given, must also be a string.
+* `path` {String}
+* `ext` {String} An optional file extension
+
+The `path.basename()` methods returns the last portion of a `path`, similar to
+the Unix `basename` command.
 
-Examples:
+For example:
 
 ```js
 path.basename('/foo/bar/baz/asdf/quux.html')
-// returns 'quux.html'
+  // returns 'quux.html'
 
 path.basename('/foo/bar/baz/asdf/quux.html', '.html')
-// returns 'quux'
+  // returns 'quux'
 ```
 
+A [`TypeError`][] is thrown if `path` is not a string or if `ext` is given
+and is not a string.
+
 ## path.delimiter
 <!-- YAML
 added: v0.9.3
 -->
 
-The platform-specific path delimiter, `;` or `':'`.
+Provides the platform-specific path delimiter:
+
+* `;` for Windows
+* `:` for POSIX
 
-An example on \*nix:
+For example, on POSIX:
 
 ```js
 console.log(process.env.PATH)
@@ -42,7 +98,7 @@ process.env.PATH.split(path.delimiter)
 // returns ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']
 ```
 
-An example on Windows:
+On Windows:
 
 ```js
 console.log(process.env.PATH)
@@ -57,27 +113,34 @@ process.env.PATH.split(path.delimiter)
 added: v0.1.16
 -->
 
-Return the directory name of a path, similar to the Unix `dirname` command.
-`path` must be a string.
+* `path` {String}
 
-Example:
+The `path.dirname()` method returns the directory name of a `path`, similar to
+the Unix `dirname` command.
+
+For example:
 
 ```js
 path.dirname('/foo/bar/baz/asdf/quux')
 // returns '/foo/bar/baz/asdf'
 ```
 
+A [`TypeError`][] is thrown if `path` is not a string.
+
 ## path.extname(path)
 <!-- YAML
 added: v0.1.25
 -->
 
-Return the extension of the path, from the last '.' to end of string
-in the last portion of the path.  If there is no '.' in the last portion
-of the path or the first character of it is '.', then it returns
-an empty string. `path` must be a string.
+* `path` {String}
 
-Examples:
+The `path.extname()` method returns the extension of the `path`, from the last
+occurance of the `.` (period) character to end of string in the last portion of
+the `path`.  If there is no `.` in the last portion of the `path`, or if the
+first character of the basename of `path` (see `path.basename()`) is `.`, then
+an empty string is returned.
+
+For example:
 
 ```js
 path.extname('index.html')
@@ -96,66 +159,73 @@ path.extname('.index')
 // returns ''
 ```
 
+A [`TypeError`][] is thrown if `path` is not a string.
+
 ## path.format(pathObject)
 <!-- YAML
 added: v0.11.15
 -->
 
-Returns a path string from an object. This is the opposite of [`path.parse`][].
+* `pathObject` {Object}
+  * `dir` {String}
+  * `root` {String} 
+  * `base` {String}
+  * `name` {String}
+  * `ext` {String}
 
-If `pathObject` has `dir` and `base` properties, the returned string will
-be a concatenation of the `dir` property, the platform-dependent path separator,
-and the `base` property.
+The `path.format()` method returns a path string from an object. This is the
+opposite of [`path.parse()`][].
 
-If the `dir` property is not supplied, the `root` property will be used as the
-`dir` property. However, it will be assumed that the `root` property already
-ends with the platform-dependent path separator. In this case, the returned
-string will be the concatenation of the `root` property and the `base` property.
+The following process is used when constructing the path string:
 
-If both the `dir` and the `root` properties are not supplied, then the returned
-string will be the contents of the `base` property.
+* `output` is set to an empty string.
+* If `pathObject.dir` is specified, `pathObject.dir` is appended to `output`
+  followed by the value of `path.sep`;
+* Otherwise, if `pathObject.root` is specified, `pathObject.root` is appended
+  to `output`.
+* If `pathObject.base` is specified, `pathObject.base` is appended to `output`;
+* Otherwise:
+  * If `pathObject.name` is specified, `pathObject.name` is appended to `output`
+  * If `pathObject.ext` is specified, `pathObject.ext` is appended to `output`.
+* Return `output`
 
-If the `base` property is not supplied, a concatenation of the `name` property
-and the `ext` property will be used as the `base` property.
-
-Examples:
-
-Some Posix system examples:
+For example, on POSIX:
 
 ```js
-// If `dir` and `base` are provided, `dir` + platform separator + `base`
+// If `dir` and `base` are provided,
+// `${dir}${path.sep}${base}`
 // will be returned.
 path.format({
-    dir: '/home/user/dir',
-    base: 'file.txt'
+  dir: '/home/user/dir',
+  base: 'file.txt'
 });
 // returns '/home/user/dir/file.txt'
 
 // `root` will be used if `dir` is not specified.
-// `name` + `ext` will be used if `base` is not specified.
 // If only `root` is provided or `dir` is equal to `root` then the
 // platform separator will not be included.
 path.format({
-    root: '/',
-    base: 'file.txt'
+  root: '/',
+  base: 'file.txt'
 });
 // returns '/file.txt'
 
+// `name` + `ext` will be used if `base` is not specified.
 path.format({
-    dir: '/',
-    root: '/',
-    name: 'file',
-    ext: '.txt'
+  root: '/',
+  name: 'file',
+  ext: '.txt'
 });
 // returns '/file.txt'
 
 // `base` will be returned if `dir` or `root` are not provided.
 path.format({
-    base: 'file.txt'
+  base: 'file.txt'
 });
 // returns 'file.txt'
 ```
-An example on Windows:
+
+On Windows:
 
 ```js
 path.format({
@@ -173,11 +243,13 @@ path.format({
 added: v0.11.2
 -->
 
-Determines whether `path` is an absolute path. An absolute path will always
-resolve to the same location, regardless of the working directory. `path` must
-be a string.
+* `path` {String}
+
+The `path.isAbsolute()` method determines if `path` is an absolute path.
+
+If the given `path` is a zero-length string, `false` will be returned.
 
-Examples on \*nix:
+For example on POSIX:
 
 ```js
 path.isAbsolute('/foo/bar') // true
@@ -186,7 +258,7 @@ path.isAbsolute('qux/')     // false
 path.isAbsolute('.')        // false
 ```
 
-Examples on Windows:
+On Windows:
 
 ```js
 path.isAbsolute('//server')  // true
@@ -195,66 +267,86 @@ 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.
+A [`TypeError`][] is thrown if `path` is not a string.
 
-## path.join([path1][, path2][, ...])
+## path.join([path[, ...]])
 <!-- YAML
 added: v0.1.16
 -->
 
-Join all arguments together and normalize the resulting path.
+* `[path[, ...]]` {String} A sequence of path segments
 
-All arguments must be strings.  In v0.8, non-string arguments were
-silently ignored.  In v0.10 and up, an exception is thrown.
+The `path.join()` method join all given `path` segments together using the
+platform specific separator as a delimiter, then normalizes the resulting path.
 
-Examples:
+Zero-length `path` segments are ignored. If the joined path string is a
+zero-length string then `'.'` will be returned, representing the current
+working directory.
+
+For example:
 
 ```js
 path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
 // returns '/foo/bar/baz/asdf'
 
 path.join('foo', {}, 'bar')
-// throws exception
-TypeError: Arguments to path.join must be strings
+// throws 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.
+A [`TypeError`][] is thrown if any of the path segments is not a string.
 
 ## path.normalize(path)
 <!-- YAML
 added: v0.1.23
 -->
 
-Normalize a path, taking care of `'..'` and `'.'` parts. `path` must be a
-string.
+* `path` {String}
+
+The `path.normalize()` method normalizes the given `path`, resolving `'..'` and
+`'.'` segments.
 
-When multiple slashes are found, they're replaced by a single one;
-when the path contains a trailing slash, it is preserved.
-On Windows backslashes are used.
+When multiple, sequential path segment separation characters are found (e.g.
+`/` on POSIX and `\` on Windows), they are replaced by a single instance of the
+platform specific path segment separator. Trailing separators are preserved.
 
-Example:
+If the `path` is a zero-length string, `'.'` is returned, representing the
+current working directory.
+
+For example on POSIX:
 
 ```js
 path.normalize('/foo/bar//baz/asdf/quux/..')
 // 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.
+On Windows:
+
+```js
+path.normalize('C:\\temp\\\\foo\\bar\\..\\');
+// returns 'C:\\temp\\foo\\'
+```
+
+A [`TypeError`][] is thrown if `path` is not a string.
 
 ## path.parse(path)
 <!-- YAML
 added: v0.11.15
 -->
 
-Returns an object from a path. `path` must be a string.
+* `path` {String}
+
+The `path.parse()` method returns an object whose properties represent
+significant elements of the `path`.
+
+The returned object will have the following properties:
+
+* `root` {String}
+* `dir` {String}
+* `base` {String}
+* `ext` {String}
+* `name` {String}
 
-An example on \*nix:
+For example on POSIX:
 
 ```js
 path.parse('/home/user/dir/file.txt')
@@ -268,91 +360,108 @@ path.parse('/home/user/dir/file.txt')
 // }
 ```
 
-An example on Windows:
+```text
+┌─────────────────────┬────────────┐
+│          dir        │    base    │
+├──────┬              ├──────┬─────┤
+│ root │              │ name │ ext │
+"  /    home/user/dir / file  .txt "
+└──────┴──────────────┴──────┴─────┘
+(all spaces in the "" line should be ignored -- they're purely for formatting)
+```
+
+On Windows:
 
 ```js
-path.parse('C:\\path\\dir\\index.html')
+path.parse('C:\\path\\dir\\file.txt')
 // returns
 // {
 //    root : "C:\\",
 //    dir : "C:\\path\\dir",
-//    base : "index.html",
-//    ext : ".html",
-//    name : "index"
+//    base : "file.txt",
+//    ext : ".txt",
+//    name : "file"
 // }
 ```
 
+```text
+┌─────────────────────┬────────────┐
+│          dir        │    base    │
+├──────┬              ├──────┬─────┤
+│ root │              │ name │ ext │
+" C:\      path\dir   \ file  .txt "
+└──────┴──────────────┴──────┴─────┘
+(all spaces in the "" line should be ignored -- they're purely for formatting)
+```
+
+A [`TypeError`][] is thrown if `path` is not a string.
+
 ## path.posix
 <!-- YAML
 added: v0.11.15
 -->
 
-Provide access to aforementioned `path` methods but always interact in a posix
-compatible way.
+The `path.posix` property provides access to POSIX specific implementations
+of the `path` methods.
 
 ## path.relative(from, to)
 <!-- YAML
 added: v0.5.0
 -->
 
-Solve the relative path from `from` to `to`. `from` and `to` must be strings.
+* `from` {String}
+* `to` {String}
+
+The `path.relative()` method returns the relative path from `from` to `to`.
+If `from` and `to` each resolve to the same path (after calling `path.resolve()`
+on each), a zero-length string is returned.
 
-At times we have two absolute paths, and we need to derive the relative
-path from one to the other.  This is actually the reverse transform of
-`path.resolve`, which means we see that:
+If a zero-length string is passed as `from` or `to`, the current working
+directory will be used instead of the zero-length strings.
+
+For example on POSIX:
 
 ```js
-path.resolve(from, path.relative(from, to)) == path.resolve(to)
+path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
+// returns '../../impl/bbb'
 ```
 
-Examples:
+On Windows:
 
 ```js
 path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb')
 // returns '..\\..\\impl\\bbb'
-
-path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
-// 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.
+A [`TypeError`][] is thrown if neither `from` nor `to` is a string.
 
-## path.resolve([from ...], to)
+## path.resolve([path[, ...]])
 <!-- YAML
 added: v0.3.4
 -->
 
-Resolves `to` to an absolute path. All arguments must be strings.
+* `[path[, ...]]` {String} A sequence of paths or path segments
 
-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. Empty string `from` arguments are
-ignored.
+The `path.resolve()` method resolves a sequence of paths or path segments into
+an absolute path.
 
-Another way to think of it is as a sequence of `cd` commands in a shell.
+The given sequence of paths is processed from right to left, with each
+subsequent `path` prepended until an absolute path is constructed.
+For instance, given the sequence of path segments: `/foo`, `/bar`, `baz`,
+calling `path.resolve('/foo', '/bar', 'baz')` would return `/bar/baz`.
 
-```js
-path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
-```
+If after processing all given `path` segments an absolute path has not yet
+been generated, the current working directory is used.
 
-Is similar to:
+The resulting path is normalized and trailing slashes are removed unless the
+path is resolved to the root directory.
 
-```
-cd foo/bar
-cd /tmp/file/
-cd ..
-cd a/../subfile
-pwd
-```
+Zero-length `path` segments are ignored.
 
-The difference is that the different paths don't need to exist and may also be
-files.
+If no `path` segments are passed, `path.resolve()` will return the absolute path
+of the current working directory.
 
-Examples:
+For example:
 
 ```js
 path.resolve('/foo/bar', './baz')
@@ -362,25 +471,30 @@ path.resolve('/foo/bar', '/tmp/file/')
 // returns '/tmp/file'
 
 path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')
-// if currently in /home/myself/node, it returns
-// '/home/myself/node/wwwroot/static_files/gif/image.gif'
+// if the current working directory is /home/myself/node,
+// this returns '/home/myself/node/wwwroot/static_files/gif/image.gif'
 ```
 
+A [`TypeError`][] is thrown if any of the arguments is not a string.
+
 ## path.sep
 <!-- YAML
 added: v0.7.9
 -->
 
-The platform-specific file separator. `'\\'` or `'/'`.
+Provides the platform-specific path segment separator:
+
+* `\` on Windows
+* `/` on POSIX
 
-An example on \*nix:
+For example on POSIX:
 
 ```js
 'foo/bar/baz'.split(path.sep)
 // returns ['foo', 'bar', 'baz']
 ```
 
-An example on Windows:
+On Windows:
 
 ```js
 'foo\\bar\\baz'.split(path.sep)
@@ -392,7 +506,10 @@ An example on Windows:
 added: v0.11.15
 -->
 
-Provide access to aforementioned `path` methods but always interact in a win32
-compatible way.
+The `path.win32` property provides access to Windows-specific implementations
+of the `path` methods.
 
-[`path.parse`]: #path_path_parse_path
+[`path.posix`]: #path_path_posix
+[`path.win32`]: #path_path_win32
+[`path.parse()`]: #path_path_parse_path
+[`TypeError`]: errors.html#errors_class_typeerror