1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: unify dirname and filename description

Browse Source 
__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>
This commit is contained in:
Sam Roberts 2016-12-29 14:11:02 -08:00
parent 6e2f8a421b
commit 134481dbe9
1 changed files with 32 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
doc/api/globals.md
View File

@ -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
@ -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
@ -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