From 49fd6add68ca550e87e7af40994eb5e9e3e8d04a Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 13 Mar 2016 13:40:25 -0700 Subject: [PATCH] doc: explain path.format() algorithm PR-URL: https://github.com/nodejs/node/pull/5688 Reviewed-By: Benjamin Gruenbaum Reviewed-By: Claudio Rodriguez Reviewed-By: James M Snell Fixes: https://github.com/nodejs/node/issues/2305 --- 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 7cd7abd5dd682b..b9132bc0c66a71 100644 --- 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({