Skip to content

Commit 9544c5e

Browse files
committed
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.
1 parent b801e39 commit 9544c5e

File tree

1 file changed

+36
-56
lines changed

1 file changed

+36
-56
lines changed

doc/api/path.markdown

Lines changed: 36 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,10 @@ Example:
1616

1717
```js
1818
path.basename('/foo/bar/baz/asdf/quux.html')
19-
// returns
20-
'quux.html'
19+
// returns 'quux.html'
2120

2221
path.basename('/foo/bar/baz/asdf/quux.html', '.html')
23-
// returns
24-
'quux'
22+
// returns 'quux'
2523
```
2624

2725
## path.delimiter
@@ -35,8 +33,7 @@ console.log(process.env.PATH)
3533
// '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin'
3634

3735
process.env.PATH.split(path.delimiter)
38-
// returns
39-
['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']
36+
// returns ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']
4037
```
4138

4239
An example on Windows:
@@ -46,8 +43,7 @@ console.log(process.env.PATH)
4643
// 'C:\Windows\system32;C:\Windows;C:\Program Files\node\'
4744

4845
process.env.PATH.split(path.delimiter)
49-
// returns
50-
['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\']
46+
// returns ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\']
5147
```
5248

5349
## path.dirname(p)
@@ -58,8 +54,7 @@ Example:
5854

5955
```js
6056
path.dirname('/foo/bar/baz/asdf/quux')
61-
// returns
62-
'/foo/bar/baz/asdf'
57+
// returns '/foo/bar/baz/asdf'
6358
```
6459

6560
## path.extname(p)
@@ -71,24 +66,19 @@ an empty string. Examples:
7166

7267
```js
7368
path.extname('index.html')
74-
// returns
75-
'.html'
69+
// returns '.html'
7670

7771
path.extname('index.coffee.md')
78-
// returns
79-
'.md'
72+
// returns '.md'
8073

8174
path.extname('index.')
82-
// returns
83-
'.'
75+
// returns '.'
8476

8577
path.extname('index')
86-
// returns
87-
''
78+
// returns ''
8879

8980
path.extname('.index')
90-
// returns
91-
''
81+
// returns ''
9282
```
9383

9484
## path.format(pathObject)
@@ -102,9 +92,8 @@ path.format({
10292
base : "file.txt",
10393
ext : ".txt",
10494
name : "file"
105-
})
106-
// returns
107-
'/home/user/dir/file.txt'
95+
});
96+
// returns '/home/user/dir/file.txt'
10897

10998
// `root` will be used if `dir` is not specified and `name` + `ext` will be used
11099
// if `base` is not specified
@@ -113,8 +102,7 @@ path.format({
113102
ext : ".txt",
114103
name : "file"
115104
})
116-
// returns
117-
'/file.txt'
105+
// returns '/file.txt'
118106
```
119107

120108
## path.isAbsolute(path)
@@ -155,8 +143,7 @@ Example:
155143

156144
```js
157145
path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
158-
// returns
159-
'/foo/bar/baz/asdf'
146+
// returns '/foo/bar/baz/asdf'
160147

161148
path.join('foo', {}, 'bar')
162149
// throws exception
@@ -180,8 +167,7 @@ Example:
180167

181168
```js
182169
path.normalize('/foo/bar//baz/asdf/quux/..')
183-
// returns
184-
'/foo/bar/baz/asdf'
170+
// returns '/foo/bar/baz/asdf'
185171
```
186172

187173
*Note:* If the path string passed as argument is a zero-length string then `'.'`
@@ -196,27 +182,27 @@ An example on \*nix:
196182
```js
197183
path.parse('/home/user/dir/file.txt')
198184
// returns
199-
{
200-
root : "/",
201-
dir : "/home/user/dir",
202-
base : "file.txt",
203-
ext : ".txt",
204-
name : "file"
205-
}
185+
// {
186+
// root : "/",
187+
// dir : "/home/user/dir",
188+
// base : "file.txt",
189+
// ext : ".txt",
190+
// name : "file"
191+
// }
206192
```
207193

208194
An example on Windows:
209195

210196
```js
211197
path.parse('C:\\path\\dir\\index.html')
212198
// returns
213-
{
214-
root : "C:\\",
215-
dir : "C:\\path\\dir",
216-
base : "index.html",
217-
ext : ".html",
218-
name : "index"
219-
}
199+
// {
200+
// root : "C:\\",
201+
// dir : "C:\\path\\dir",
202+
// base : "index.html",
203+
// ext : ".html",
204+
// name : "index"
205+
// }
220206
```
221207

222208
## path.posix
@@ -240,12 +226,10 @@ Examples:
240226

241227
```js
242228
path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb')
243-
// returns
244-
'..\\..\\impl\\bbb'
229+
// returns '..\\..\\impl\\bbb'
245230

246231
path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
247-
// returns
248-
'../../impl/bbb'
232+
// returns '../../impl/bbb'
249233
```
250234

251235
*Note:* If the arguments to `relative` have zero-length strings then the current
@@ -285,16 +269,14 @@ Examples:
285269

286270
```js
287271
path.resolve('/foo/bar', './baz')
288-
// returns
289-
'/foo/bar/baz'
272+
// returns '/foo/bar/baz'
290273

291274
path.resolve('/foo/bar', '/tmp/file/')
292-
// returns
293-
'/tmp/file'
275+
// returns '/tmp/file'
294276

295277
path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')
296278
// if currently in /home/myself/node, it returns
297-
'/home/myself/node/wwwroot/static_files/gif/image.gif'
279+
// '/home/myself/node/wwwroot/static_files/gif/image.gif'
298280
```
299281

300282
*Note:* If the arguments to `resolve` have zero-length strings then the current
@@ -308,16 +290,14 @@ An example on \*nix:
308290

309291
```js
310292
'foo/bar/baz'.split(path.sep)
311-
// returns
312-
['foo', 'bar', 'baz']
293+
// returns ['foo', 'bar', 'baz']
313294
```
314295

315296
An example on Windows:
316297

317298
```js
318299
'foo\\bar\\baz'.split(path.sep)
319-
// returns
320-
['foo', 'bar', 'baz']
300+
// returns ['foo', 'bar', 'baz']
321301
```
322302

323303
## path.win32

0 commit comments

Comments
 (0)