From b8ae1b86d44133dcb179008cd22b0e4d60766c0e Mon Sep 17 00:00:00 2001
From: John Eversole <eversojk@gmail.com>
Date: Mon, 21 Mar 2016 18:20:16 -0700
Subject: [PATCH] doc: path.format provide more examples

This change was to add upon the algorithm description of path.format
by adding examples for unix systems that clarified behavior in
various scenarios.

PR-URL: https://github.com/nodejs/node/pull/5838
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Roman Klauke <romaaan.git@gmail.com>
---
 doc/api/path.markdown | 39 ++++++++++++++++++++++++++++++++-------
 1 file changed, 32 insertions(+), 7 deletions(-)

diff --git a/doc/api/path.markdown b/doc/api/path.markdown
index b1110e7f21aa0b..07f4a07a9282fb 100644
--- a/doc/api/path.markdown
+++ b/doc/api/path.markdown
@@ -92,7 +92,7 @@ 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.
+string will be the concatenation of 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.
@@ -100,17 +100,42 @@ 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.
 
-An example on Posix systems:
+Examples:
+
+Some Posix system examples:
 
 ```js
+// If `dir` and `base` are provided, `dir` + platform separator + `base`
+// will be returned.
 path.format({
-    root : "/",
-    dir : "/home/user/dir",
-    base : "file.txt",
-    ext : ".txt",
-    name : "file"
+    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'
+});
+// returns '/file.txt'
+
+path.format({
+    dir: '/',
+    root: '/',
+    name: 'file',
+    ext: '.txt'
+});
+// returns '/file.txt'
+
+// `base` will be returned if `dir` or `root` are not provided.
+path.format({
+    base: 'file.txt'
+});
+// returns 'file.txt'
 ```
 
 An example on Windows: