Skip to content

Commit 0943001

Browse files
TrottMyles Borins
authored and
Myles Borins
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. PR-URL: #5797 Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent bb423bb commit 0943001

File tree

1 file changed

+44
-53
lines changed

1 file changed

+44
-53
lines changed

doc/api/path.markdown

+44-53
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)
@@ -117,10 +107,19 @@ path.format({
117107
base : "file.txt",
118108
ext : ".txt",
119109
name : "file"
110+
});
111+
// returns '/home/user/dir/file.txt'
112+
113+
// `root` will be used if `dir` is not specified and `name` + `ext` will be used
114+
// if `base` is not specified
115+
path.format({
116+
root : "/",
117+
ext : ".txt",
118+
name : "file"
120119
})
121-
// returns
122-
'/home/user/dir/file.txt'
120+
// returns '/file.txt'
123121
```
122+
124123
## path.isAbsolute(path)
125124

126125
Determines whether `path` is an absolute path. An absolute path will always
@@ -159,8 +158,7 @@ Example:
159158

160159
```js
161160
path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
162-
// returns
163-
'/foo/bar/baz/asdf'
161+
// returns '/foo/bar/baz/asdf'
164162

165163
path.join('foo', {}, 'bar')
166164
// throws exception
@@ -184,8 +182,7 @@ Example:
184182

185183
```js
186184
path.normalize('/foo/bar//baz/asdf/quux/..')
187-
// returns
188-
'/foo/bar/baz/asdf'
185+
// returns '/foo/bar/baz/asdf'
189186
```
190187

191188
*Note:* If the path string passed as argument is a zero-length string then `'.'`
@@ -200,27 +197,27 @@ An example on \*nix:
200197
```js
201198
path.parse('/home/user/dir/file.txt')
202199
// returns
203-
{
204-
root : "/",
205-
dir : "/home/user/dir",
206-
base : "file.txt",
207-
ext : ".txt",
208-
name : "file"
209-
}
200+
// {
201+
// root : "/",
202+
// dir : "/home/user/dir",
203+
// base : "file.txt",
204+
// ext : ".txt",
205+
// name : "file"
206+
// }
210207
```
211208

212209
An example on Windows:
213210

214211
```js
215212
path.parse('C:\\path\\dir\\index.html')
216213
// returns
217-
{
218-
root : "C:\\",
219-
dir : "C:\\path\\dir",
220-
base : "index.html",
221-
ext : ".html",
222-
name : "index"
223-
}
214+
// {
215+
// root : "C:\\",
216+
// dir : "C:\\path\\dir",
217+
// base : "index.html",
218+
// ext : ".html",
219+
// name : "index"
220+
// }
224221
```
225222

226223
## path.posix
@@ -244,12 +241,10 @@ Examples:
244241

245242
```js
246243
path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb')
247-
// returns
248-
'..\\..\\impl\\bbb'
244+
// returns '..\\..\\impl\\bbb'
249245

250246
path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
251-
// returns
252-
'../../impl/bbb'
247+
// returns '../../impl/bbb'
253248
```
254249

255250
*Note:* If the arguments to `relative` have zero-length strings then the current
@@ -289,16 +284,14 @@ Examples:
289284

290285
```js
291286
path.resolve('/foo/bar', './baz')
292-
// returns
293-
'/foo/bar/baz'
287+
// returns '/foo/bar/baz'
294288

295289
path.resolve('/foo/bar', '/tmp/file/')
296-
// returns
297-
'/tmp/file'
290+
// returns '/tmp/file'
298291

299292
path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')
300293
// if currently in /home/myself/node, it returns
301-
'/home/myself/node/wwwroot/static_files/gif/image.gif'
294+
// '/home/myself/node/wwwroot/static_files/gif/image.gif'
302295
```
303296

304297
*Note:* If the arguments to `resolve` have zero-length strings then the current
@@ -312,16 +305,14 @@ An example on \*nix:
312305

313306
```js
314307
'foo/bar/baz'.split(path.sep)
315-
// returns
316-
['foo', 'bar', 'baz']
308+
// returns ['foo', 'bar', 'baz']
317309
```
318310

319311
An example on Windows:
320312

321313
```js
322314
'foo\\bar\\baz'.split(path.sep)
323-
// returns
324-
['foo', 'bar', 'baz']
315+
// returns ['foo', 'bar', 'baz']
325316
```
326317

327318
## path.win32

0 commit comments

Comments
 (0)