From 93391ae9cb162dc79d3307b0e7767f5f505a5c69 Mon Sep 17 00:00:00 2001 From: Ryan Graham Date: Mon, 8 Apr 2013 09:59:15 -0700 Subject: [PATCH] doc: clarify exports and module.exports When exporting a single function you must use `module.exports` instead of the `exports` convenience reference. --- doc/api/globals.markdown | 7 ++++--- doc/api/modules.markdown | 16 +++++++++++++++- 2 files changed, 19 insertions(+), 4 deletions(-) diff --git a/doc/api/globals.markdown b/doc/api/globals.markdown index bc2996b..2f797be 100644 --- a/doc/api/globals.markdown +++ b/doc/api/globals.markdown @@ -133,9 +133,10 @@ See the [module system documentation][] for more information. -An object which is shared between all instances of the current module and -made accessible through `require()`. -`exports` is the same as the `module.exports` object. +A reference to the `module.exports` object which is shared between all +instances of the current module and made accessible through `require()`. +See [module system documentation][] for details on when to use `exports` and +when to use `module.exports`. `exports` isn't actually a global but rather local to each module. See the [module system documentation][] for more information. diff --git a/doc/api/modules.markdown b/doc/api/modules.markdown index 4720aa5..95e3012 100644 --- a/doc/api/modules.markdown +++ b/doc/api/modules.markdown @@ -30,6 +30,20 @@ The module `circle.js` has exported the functions `area()` and `circumference()`. To export an object, add to the special `exports` object. +Note that `exports` is a reference to `module.exports` making it suitable +for augmentation only. If you are exporting a single item such as a +constructor you will want to use `module.exports` directly instead. + + function MyConstructor (opts) { + //... + } + + // BROKEN: Does not modify exports + exports = MyConstructor; + + // exports the constructor properly + module.exports = MyConstructor; + Variables local to the module will be private. In this example the variable `PI` is private to `circle.js`. @@ -219,7 +233,7 @@ would resolve to different files. In each module, the `module` free variable is a reference to the object representing the current module. In particular -`module.exports` is the same as the `exports` object. +`module.exports` is accessible via the `exports` module-global. `module` isn't actually a global but rather local to each module. ### module.exports -- 2.7.4