Skip to content

doc: add more detailed illustration for module.exports and exports. #9552

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

doc: add more detailed illustration for module.exports and exports. #9552

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e7b819f
doc: add more detailed illustration for `module.exports` and `exports`.
iamchenxin Nov 10, 2016
b382dc6
fix some style, grammar, formatting, error.
iamchenxin Nov 13, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
fix some style, grammar, formatting, error. 
Line wrap at 80 columns.
comma splice.
`The module wrapper` to [module wrapper](#modules_the_module_wrapper)
parenthesis error.
  • Loading branch information
@iamchenxin
iamchenxin committed Nov 13, 2016
commit b382dc65bd40e5cb7dd5b6b83a3263ce4d696055
32 changes: 18 additions & 14 deletions doc/api/modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -481,23 +481,26 @@ added: v0.1.16

* {Object}

`module.exports` object is used to export values in a js file. It is
initialized as `{}` by Module system, and passed to `The module wrapper` as argument(This makes `module.exports` and `exports` available in a js file,
the details will be described below). `require` return the processed
`module.exports` as the exports of a module.
The `module.exports` object is used to export values in a js file. It is
initialized as `{}` by Module system, and passed to
[module wrapper](#modules_the_module_wrapper) as argument. (This makes
Copy link
Contributor

@sam-github sam-github Nov 14, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"as an argument". Remove the parentheses around the complete sentence.

Copy link
Member

@jasnell jasnell Nov 18, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: replace:

... a js file.

with:

... `*.js` files.

`module.exports` and `exports` available in a js file, the details will be
Copy link
Contributor

@sam-github sam-github Nov 14, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

", the details..." unnecessary, remove, or replace with a "see LINK" that links to the docs.

described below.) `require` returns the processed `module.exports` as the
exports of a module.

#### exports alias
<!-- YAML
added: v0.1.16
-->

There is no magic behind `exports`, it is the `module.exports` passed to
`The module wrapper` as the first argument.
There is no magic behind `exports`. It is the `module.exports` passed to
Copy link
Contributor

@sam-github sam-github Nov 14, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove "there is no magic" phrase, it adds no value. "It is the" change to "exports is an alias to the". Link module.exports to its docs.

Copy link
Contributor Author

@iamchenxin iamchenxin Nov 15, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The key point of this sentence is i want to remove the alias, because of this word make some one like me very confused , till check the source code. alias tend to refer to something like reference, imply the things happened in export will reflect into module.export. But it is indeed a value copy from module.export by argument.
I am not sure how to describe this rightly.

[module wrapper](#modules_the_module_wrapper) as the first argument.

Here is a minimized code logic of `require` to illustrate the export principle,
and how `module.exports` and `exports` works:<br/>
Here is a minimized code logic of `require` to illustrate the export
principle, and how `module.exports` and `exports` works:<br/>

As described in `The module wrapper`, your js file will be wrapped like this:
As described in [module wrapper](#modules_the_module_wrapper), your js file
Copy link
Contributor

@sam-github sam-github Nov 14, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

js -> Javascript

Copy link
Member

@jasnell jasnell Nov 18, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please avoid the use of informal pronouns such as 'you', 'your', 'us', etc.

will be wrapped like this:
```js
(function (exports, require, module, __filename, __dirname) { // fileWrapper
// Your module code actually lives in here
Expand Down Expand Up @@ -529,10 +532,10 @@ points:
As a result, the export results of a module is a returned value of
`module.exports` at the tickcount which `require` is returned.
Copy link
Contributor

@sam-github sam-github Nov 14, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is not true

Copy link
Contributor Author

@iamchenxin iamchenxin Nov 15, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the behaviors of this. I thought whenever the user do anything in a file 'x.js', the result of require('./x.js') in 'y.js', will always be the returned value of module.exports.
Because my English is poor, so sorry for my inexactly description.

Copy link
Contributor

@sam-github sam-github Nov 15, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

// module "hello.js"
module.exports.yes = true;
setTimeout(function() {
module.exports.yes = false;
module.exports.somethingElse = true;
}, 1000);

I don't know exactly what you are trying to say, but I believe you are saying require(..../hello.js).yes === true always and forevere because it was true in the tick that require was called, but that isn't true. 1 second after the require, the module's API value will change.

Copy link
Contributor Author

@iamchenxin iamchenxin Nov 15, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nope, i want to say it is the value of the returned module.exports.
Cause in Javascript value of an Object is a memory location(or Handle?).
not sure how to describe the term value rightly. ( and there is a term deep value in Javascript, but in some place the value is used to refer to deep value).

Copy link
Contributor Author

@iamchenxin iamchenxin Nov 15, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is why i write a pseudo code for require, a pseudo code will always exactly and cross langauges and terms. (But if i am good at English, may be i do not need that pseudo code to explain what it should be.)


Let's illustrate the behaviors and principles with codes. ( You can use either
`_require` or directly a js file to check these behaviors. )
Let's illustrate the behaviors and principles with codes. (You can use either
Copy link
Contributor

@sam-github sam-github Nov 14, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Trott is this colloquial "let's" and "you" used in node documentation?

"codes" -> "code"

`_require` or directly a js file to check these behaviors.)

Synchronize behaviors( Demonstrate with the minimized `_require` above ):
Synchronize behaviors (Demonstrate with the minimized `_require` above) :
```js
function synchronize(exports, _, module) { // the module wrapper
Copy link
Contributor

@sam-github sam-github Nov 14, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is not a useful way to describe how to write modules, since users do not actually write modules like this

// Your module codes actually lives below:
Expand Down Expand Up @@ -561,7 +564,7 @@ console.log(exported);
*/
```

Asynchronous behaviors ( directly check in file):<br/>
Asynchronous behaviors (directly checking in file) :<br/>
Assume you have a `x.js`:
```js
// Let's name the exported value, to make things clearly.
Expand Down Expand Up @@ -591,7 +594,8 @@ setTimeout( () => {
There is one more thing to notice: `this`. Because `module.exports` was passed
as `this` argument for `The module wrapper`, you may used `this` as an alias of
`exports` to export values previously, But since `this` is an undocumented
value, the behavior of `this` is not guaranteed. Ex: when you use `babel`, `transform-es2015-modules-commonjs` will break `this`, so you should not use
value, the behavior of `this` is not guaranteed. Ex: when you use `babel`,
`transform-es2015-modules-commonjs` will break `this`, so you should not use
`this` as a shortcut for export.
Copy link
Contributor

@sam-github sam-github Nov 14, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't agree with the above. this is documented, its documented right here! And if the module does not work when some random thirdparty tool is used to convert it to some other form... that should be part of that tools documentation, not proposed as a general rule for node modules.

Copy link
Contributor Author

@iamchenxin iamchenxin Nov 15, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did do find this in old module docs. searched in doc/api/module.md again previously.


**As a guideline**, never use 'this' to export, and if the `exports` and
Expand Down