doc: explain path.format() algorithm

PR-URL: https://github.com/nodejs/node/pull/5688
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Claudio Rodriguez <cjrodr@yahoo.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Fixes: https://github.com/nodejs/node/issues/2305

diff --git a/doc/api/path.markdown b/doc/api/path.markdown
index 7cd7abd..b9132bc 100644 (file)
--- a/doc/api/path.markdown
+++ b/doc/api/path.markdown
@@ -93,7 +93,22 @@ path.extname('.index')
 
 ## path.format(pathObject)
 
-Returns a path string from an object, the opposite of [`path.parse`][].
+Returns a path string from an object. This is the opposite of [`path.parse`][].
+
+If `pathObject` has all expected properties, the returned string will be a
+concatenation of the `dir` property, the platform-dependent path separator, and
+the `base` property.
+
+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 fo the `root` property and the `base` property.
+
+If both the `dir` and the `root` properties are not supplied, then the returned
+string will be the contents of the `base` property.
+
+If the `base` property is not supplied, a concatenation of the `name` property
+and the `ext` property will be used as the `base` property.
 
 ```js
 path.format({