doc: clarify exports and module.exports

When exporting a single function you must use `module.exports` instead
of the `exports` convenience reference.

diff --git a/doc/api/globals.markdown b/doc/api/globals.markdown
index bc2996b..2f797be 100644 (file)
--- a/doc/api/globals.markdown
+++ b/doc/api/globals.markdown
@@ -133,9 +133,10 @@ See the [module system documentation][] for more information.
 
 <!-- type=var -->
 
-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 (file)
--- 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