Skip to content

Commit

Permalink
doc: fix invalid path doc comments
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
Trott committed Mar 14, 2016
1 parent b801e39 commit 9544c5e
Showing 1 changed file with 36 additions and 56 deletions.
92 changes: 36 additions & 56 deletions doc/api/path.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -102,9 +92,8 @@ path.format({
base : "file.txt",
ext : ".txt",
name : "file"
})
// returns
'/home/user/dir/file.txt'
});
// returns '/home/user/dir/file.txt'

// `root` will be used if `dir` is not specified and `name` + `ext` will be used
// if `base` is not specified
Expand All @@ -113,8 +102,7 @@ path.format({
ext : ".txt",
name : "file"
})
// returns
'/file.txt'
// returns '/file.txt'
```

## path.isAbsolute(path)
Expand Down Expand Up @@ -155,8 +143,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
Expand All @@ -180,8 +167,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 `'.'`
Expand All @@ -196,27 +182,27 @@ 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:

```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
Expand All @@ -240,12 +226,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
Expand Down Expand Up @@ -285,16 +269,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
Expand All @@ -308,16 +290,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
Expand Down

0 comments on commit 9544c5e

Please sign in to comment.