From 75f723c0aa61fa304590e9fb70ce49f9099cb8bb Mon Sep 17 00:00:00 2001
From: Rich Trott <rtrott@gmail.com>
Date: Fri, 11 Mar 2016 15:57:43 -0800
Subject: [PATCH] doc: fix invalid path doc comments

The format of certain code comments in the `path` documentation results
in the code blocks being invalid. I also find it confusing at least as
formatted on the website. This change is intended to improve those
comments.

PR-URL: https://github.com/nodejs/node/pull/5670
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>

Conflicts:
	doc/api/path.markdown
---
 doc/api/path.markdown | 89 +++++++++++++++++--------------------------
 1 file changed, 35 insertions(+), 54 deletions(-)

diff --git a/doc/api/path.markdown b/doc/api/path.markdown
index 2b3f39c247d647..04ad63c889cced 100644
--- a/doc/api/path.markdown
+++ b/doc/api/path.markdown
@@ -16,12 +16,10 @@ 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'
 ```
 
 ## path.delimiter
@@ -35,8 +33,7 @@ console.log(process.env.PATH)
 // '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin'
 
 process.env.PATH.split(path.delimiter)
-// returns
-['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']
+// returns ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']
 ```
 
 An example on Windows:
@@ -46,8 +43,7 @@ console.log(process.env.PATH)
 // 'C:\Windows\system32;C:\Windows;C:\Program Files\node\'
 
 process.env.PATH.split(path.delimiter)
-// returns
-['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\']
+// returns ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\']
 ```
 
 ## path.dirname(p)
@@ -58,8 +54,7 @@ Example:
 
 ```js
 path.dirname('/foo/bar/baz/asdf/quux')
-// returns
-'/foo/bar/baz/asdf'
+// returns '/foo/bar/baz/asdf'
 ```
 
 ## path.extname(p)
@@ -71,24 +66,19 @@ an empty string.  Examples:
 
 ```js
 path.extname('index.html')
-// returns
-'.html'
+// returns '.html'
 
 path.extname('index.coffee.md')
-// returns
-'.md'
+// returns '.md'
 
 path.extname('index.')
-// returns
-'.'
+// returns '.'
 
 path.extname('index')
-// returns
-''
+// returns ''
 
 path.extname('.index')
-// returns
-''
+// returns ''
 ```
 
 ## path.format(pathObject)
@@ -117,9 +107,8 @@ path.format({
     base : "file.txt",
     ext : ".txt",
     name : "file"
-})
-// returns
-'/home/user/dir/file.txt'
+});
+// returns '/home/user/dir/file.txt'
 ```
 
 ## path.isAbsolute(path)
@@ -160,8 +149,7 @@ Example:
 
 ```js
 path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
-// returns
-'/foo/bar/baz/asdf'
+// returns '/foo/bar/baz/asdf'
 
 path.join('foo', {}, 'bar')
 // throws exception
@@ -185,8 +173,7 @@ Example:
 
 ```js
 path.normalize('/foo/bar//baz/asdf/quux/..')
-// returns
-'/foo/bar/baz/asdf'
+// returns '/foo/bar/baz/asdf'
 ```
 
 *Note:* If the path string passed as argument is a zero-length string then `'.'`
@@ -201,13 +188,13 @@ An example on \*nix:
 ```js
 path.parse('/home/user/dir/file.txt')
 // returns
-{
-    root : "/",
-    dir : "/home/user/dir",
-    base : "file.txt",
-    ext : ".txt",
-    name : "file"
-}
+// {
+//    root : "/",
+//    dir : "/home/user/dir",
+//    base : "file.txt",
+//    ext : ".txt",
+//    name : "file"
+// }
 ```
 
 An example on Windows:
@@ -215,13 +202,13 @@ An example on Windows:
 ```js
 path.parse('C:\\path\\dir\\index.html')
 // returns
-{
-    root : "C:\\",
-    dir : "C:\\path\\dir",
-    base : "index.html",
-    ext : ".html",
-    name : "index"
-}
+// {
+//    root : "C:\\",
+//    dir : "C:\\path\\dir",
+//    base : "index.html",
+//    ext : ".html",
+//    name : "index"
+// }
 ```
 
 ## path.posix
@@ -245,12 +232,10 @@ Examples:
 
 ```js
 path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb')
-// returns
-'..\\..\\impl\\bbb'
+// returns '..\\..\\impl\\bbb'
 
 path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
-// returns
-'../../impl/bbb'
+// returns '../../impl/bbb'
 ```
 
 *Note:* If the arguments to `relative` have zero-length strings then the current
@@ -290,16 +275,14 @@ Examples:
 
 ```js
 path.resolve('/foo/bar', './baz')
-// returns
-'/foo/bar/baz'
+// returns '/foo/bar/baz'
 
 path.resolve('/foo/bar', '/tmp/file/')
-// returns
-'/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'
+// '/home/myself/node/wwwroot/static_files/gif/image.gif'
 ```
 
 *Note:* If the arguments to `resolve` have zero-length strings then the current
@@ -313,16 +296,14 @@ An example on \*nix:
 
 ```js
 'foo/bar/baz'.split(path.sep)
-// returns
-['foo', 'bar', 'baz']
+// returns ['foo', 'bar', 'baz']
 ```
 
 An example on Windows:
 
 ```js
 'foo\\bar\\baz'.split(path.sep)
-// returns
-['foo', 'bar', 'baz']
+// returns ['foo', 'bar', 'baz']
 ```
 
 ## path.win32