Skip to content

Commit

Permalink
doc: unify dirname and filename description
Browse files Browse the repository at this point in the history
__dirname is path.dirname(__filename), but its docs, specifically the
attempt to describe javascript scope in terms of "running" and
"executing" had drifted apart. Rework to describe one as a variation of
the other, move the example, and just describe the names in terms of the
module, and it's local variables rather than the ill defined execution
concepts.

Fix: #5525
PR-URL: #10527
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Gibson Fahnestock <[email protected]>
  • Loading branch information
sam-github authored and evanlucas committed Jan 4, 2017
1 parent 659d522 commit d08463a
Showing 1 changed file with 32 additions and 19 deletions.
51 changes: 32 additions & 19 deletions doc/api/globals.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,27 +29,20 @@ added: v0.1.27

* {String}

The name of the directory that the currently executing script resides in.
The directory name of the current module. This the same as the
[`path.dirname()`][] of the [`__filename`][].

`__dirname` isn't actually a global but rather local to each module.

Example: running `node example.js` from `/Users/mjr`

```js
console.log(__dirname);
// Prints: /Users/mjr
console.log(path.dirname(__filename));
// Prints: /Users/mjr
```

`__dirname` isn't actually a global but rather local to each module.

For instance, given two modules: `a` and `b`, where `b` is a dependency of
`a` and there is a directory structure of:

* `/Users/mjr/app/a.js`
* `/Users/mjr/app/node_modules/b/b.js`

References to `__dirname` within `b.js` will return
`/Users/mjr/app/node_modules/b` while references to `__dirname` within `a.js`
will return `/Users/mjr/app`.

## \_\_filename
<!-- YAML
added: v0.0.1
Expand All @@ -59,19 +52,36 @@ added: v0.0.1

* {String}

The filename of the code being executed. This is the resolved absolute path
of this code file. For a main program this is not necessarily the same
filename used in the command line. The value inside a module is the path
to that module file.
The file name of the current module. This is the resolved absolute path of the
current module file.

Example: running `node example.js` from `/Users/mjr`
For a main program this is not necessarily the same as the file name used in the
command line.

See [`__dirname`][] for the directory name of the current module.

`__filename` isn't actually a global but rather local to each module.

Examples:

Running `node example.js` from `/Users/mjr`

```js
console.log(__filename);
// Prints: /Users/mjr/example.js
console.log(__dirname);
// Prints: /Users/mjr
```

`__filename` isn't actually a global but rather local to each module.
Given two modules: `a` and `b`, where `b` is a dependency of
`a` and there is a directory structure of:

* `/Users/mjr/app/a.js`
* `/Users/mjr/app/node_modules/b/b.js`

References to `__filename` within `b.js` will return
`/Users/mjr/app/node_modules/b/b.js` while references to `__filename` within
`a.js` will return `/Users/mjr/app/a.js`.

## clearImmediate(immediateObject)
<!-- YAML
Expand Down Expand Up @@ -262,7 +272,10 @@ added: v0.0.1

[`setTimeout`] is described in the [timers][] section.

[`__dirname`]: #globals_dirname
[`__filename`]: #globals_filename
[`console`]: console.html
[`path.dirname()`]: path.html#path_path_dirname_path
[`process` object]: process.html#process_process
[buffer section]: buffer.html
[module system documentation]: modules.html
Expand Down

0 comments on commit d08463a

Please sign in to comment.