Browse Source

doc: unify dirname and filename description

__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: https://github.com/nodejs/node/issues/5525
PR-URL: https://github.com/nodejs/node/pull/10527
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
v6
Sam Roberts 8 years ago
parent
commit
134481dbe9
  1. 51
      doc/api/globals.md

51
doc/api/globals.md

@ -29,27 +29,20 @@ added: v0.1.27
* {String} * {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` Example: running `node example.js` from `/Users/mjr`
```js ```js
console.log(__dirname); console.log(__dirname);
// Prints: /Users/mjr // 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 ## \_\_filename
<!-- YAML <!-- YAML
added: v0.0.1 added: v0.0.1
@ -59,19 +52,36 @@ added: v0.0.1
* {String} * {String}
The filename of the code being executed. This is the resolved absolute path The file name of the current module. This is the resolved absolute path of the
of this code file. For a main program this is not necessarily the same current module file.
filename used in the command line. The value inside a module is the path
to that 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 ```js
console.log(__filename); console.log(__filename);
// Prints: /Users/mjr/example.js // 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) ## clearImmediate(immediateObject)
<!-- YAML <!-- YAML
@ -262,7 +272,10 @@ added: v0.0.1
[`setTimeout`] is described in the [timers][] section. [`setTimeout`] is described in the [timers][] section.
[`__dirname`]: #globals_dirname
[`__filename`]: #globals_filename
[`console`]: console.html [`console`]: console.html
[`path.dirname()`]: path.html#path_path_dirname_path
[`process` object]: process.html#process_process [`process` object]: process.html#process_process
[buffer section]: buffer.html [buffer section]: buffer.html
[module system documentation]: modules.html [module system documentation]: modules.html

Loading…
Cancel
Save