Commit eef7533
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: #5525
PR-URL: #10527
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>1 parent 00026cf commit eef7533
1 file changed
Lines changed: 32 additions & 19 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -29,27 +29,20 @@ added: v0.1.27 | |||
| 29 | 29 | ||
| 30 | 30 | * {String} | |
| 31 | 31 | ||
| 32 | - The name of the directory that the currently executing script resides in. | ||
| 32 | + The directory name of the current module. This the same as the | ||
| 33 | + [`path.dirname()`][] of the [`__filename`][]. | ||
| 34 | + | ||
| 35 | + `__dirname` isn't actually a global but rather local to each module. | ||
| 33 | 36 | ||
| 34 | 37 | Example: running `node example.js` from `/Users/mjr` | |
| 35 | 38 | ||
| 36 | 39 | ```js | |
| 37 | 40 | console.log(__dirname); | |
| 38 | 41 | // Prints: /Users/mjr | |
| 42 | + console.log(path.dirname(__filename)); | ||
| 43 | + // Prints: /Users/mjr | ||
| 39 | 44 | ``` | |
| 40 | 45 | ||
| 41 | - `__dirname` isn't actually a global but rather local to each module. | ||
| 42 | - | ||
| 43 | - For instance, given two modules: `a` and `b`, where `b` is a dependency of | ||
| 44 | - `a` and there is a directory structure of: | ||
| 45 | - | ||
| 46 | - * `/Users/mjr/app/a.js` | ||
| 47 | - * `/Users/mjr/app/node_modules/b/b.js` | ||
| 48 | - | ||
| 49 | - References to `__dirname` within `b.js` will return | ||
| 50 | - `/Users/mjr/app/node_modules/b` while references to `__dirname` within `a.js` | ||
| 51 | - will return `/Users/mjr/app`. | ||
| 52 | - | ||
| 53 | 46 | ## \_\_filename | |
| 54 | 47 | <!-- YAML | |
| 55 | 48 | added: v0.0.1 | |
@@ -59,19 +52,36 @@ added: v0.0.1 | |||
| 59 | 52 | ||
| 60 | 53 | * {String} | |
| 61 | 54 | ||
| 62 | - The filename of the code being executed. This is the resolved absolute path | ||
| 63 | - of this code file. For a main program this is not necessarily the same | ||
| 64 | - filename used in the command line. The value inside a module is the path | ||
| 65 | - to that module file. | ||
| 55 | + The file name of the current module. This is the resolved absolute path of the | ||
| 56 | + current module file. | ||
| 66 | 57 | ||
| 67 | - Example: running `node example.js` from `/Users/mjr` | ||
| 58 | + For a main program this is not necessarily the same as the file name used in the | ||
| 59 | + command line. | ||
| 60 | + | ||
| 61 | + See [`__dirname`][] for the directory name of the current module. | ||
| 62 | + | ||
| 63 | + `__filename` isn't actually a global but rather local to each module. | ||
| 64 | + | ||
| 65 | + Examples: | ||
| 66 | + | ||
| 67 | + Running `node example.js` from `/Users/mjr` | ||
| 68 | 68 | ||
| 69 | 69 | ```js | |
| 70 | 70 | console.log(__filename); | |
| 71 | 71 | // Prints: /Users/mjr/example.js | |
| 72 | + console.log(__dirname); | ||
| 73 | + // Prints: /Users/mjr | ||
| 72 | 74 | ``` | |
| 73 | 75 | ||
| 74 | - `__filename` isn't actually a global but rather local to each module. | ||
| 76 | + Given two modules: `a` and `b`, where `b` is a dependency of | ||
| 77 | + `a` and there is a directory structure of: | ||
| 78 | + | ||
| 79 | + * `/Users/mjr/app/a.js` | ||
| 80 | + * `/Users/mjr/app/node_modules/b/b.js` | ||
| 81 | + | ||
| 82 | + References to `__filename` within `b.js` will return | ||
| 83 | + `/Users/mjr/app/node_modules/b/b.js` while references to `__filename` within | ||
| 84 | + `a.js` will return `/Users/mjr/app/a.js`. | ||
| 75 | 85 | ||
| 76 | 86 | ## clearImmediate(immediateObject) | |
| 77 | 87 | <!-- YAML | |
@@ -255,7 +265,10 @@ added: v0.0.1 | |||
| 255 | 265 | ||
| 256 | 266 | [`setTimeout`] is described in the [timers][] section. | |
| 257 | 267 | ||
| 268 | + [`__dirname`]: #globals_dirname | ||
| 269 | + [`__filename`]: #globals_filename | ||
| 258 | 270 | [`console`]: console.html | |
| 271 | + [`path.dirname()`]: path.html#path_path_dirname_path | ||
| 259 | 272 | [`process` object]: process.html#process_process | |
| 260 | 273 | [buffer section]: buffer.html | |
| 261 | 274 | [module system documentation]: modules.html | |
0 commit comments