doc: add more detailed illustration for module.exports and exports.
#9552
Conversation
1. Since there is an illustration for `The module wrapper`, the `module.exports` could be clearly explained with the logic of source code. 2. Add notice for `this` of a module file. (Im not sure if it is a bug of `transform-es2015-modules-commonjs`, but since `this` is undocumented, i thought `babel-plugin` is free to break it.)
nodejs-github-bot
added
doc
| this, assign the desired export object to `module.exports`. Note that assigning | ||
| the desired object to `exports` will simply rebind the local `exports` variable, | ||
| which is probably not what you want to do. | ||
| `module.exports` object is used to export values in a js file. It is |
There was a problem hiding this comment.
- I don't understand why
Thewas removed as the first word of this sentence. - Do not use
jsas an abbreviation forJavaScript.
There was a problem hiding this comment.
The must be my style error.
I am not sure how to name that? a module? a module file? a Javascript file? or help me to get a right word for this.
| the desired object to `exports` will simply rebind the local `exports` variable, | ||
| which is probably not what you want to do. | ||
| `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, |
There was a problem hiding this comment.
- Line wrap at 80 columns
- Do not put
The module wrapperin backticks. - Put a space before the opening parenthesis.
- Move parenthetical to its own sentence and include punctuation.
| which is probably not what you want to do. | ||
| `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` 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. |
There was a problem hiding this comment.
I'm not 100% sure what is meant by "the exports of a module" but I'm pretty sure that phrasing can be clarified.
There was a problem hiding this comment.
Im not sure how to name this, could you help me.
| module.exports.emit('ready'); | ||
| }, 1000); | ||
| ``` | ||
| There is no magic behind `exports`, it is the `module.exports` passed to |
| }, 1000); | ||
| ``` | ||
| There is no magic behind `exports`, it is the `module.exports` passed to | ||
| `The module wrapper` as the first argument. |
There was a problem hiding this comment.
No back ticks and no capitalization of The in The module wrapper. Are you trying to make it a link or something? I'm puzzled by the repeated backticks.
There was a problem hiding this comment.
Cause The module wrapper is a term which name previously, i thought i would has a backticks.
There was a problem hiding this comment.
makes The module wrapper to module wrapper
|
@Trott Thanks for your reviewing. Im poor at english, so very sorry for my style, grammar, formatting and etc. Will try to make this better, and it would be nice if there is some one to help me to get a qualified content. |
Line wrap at 80 columns. comma splice. `The module wrapper` to [module wrapper](#modules_the_module_wrapper) parenthesis error.
|
Leaving "js file" and "the exports of a module" unmodified, im not sure what are suitable phrases for them, please help me. |
|
I'll do the editing if no one more qualified jumps in, but I'd love it if someone else (maybe from @nodejs/documentation) volunteered. Might be a good idea to get a review of the contents first. Anyone? Also: Opinions as to whether this belongs in the modules doc or if it's the type of material that might be better as a separate guide. @nodejs/collaborators |
| which is probably not what you want to do. | ||
| 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 |
There was a problem hiding this comment.
"as an argument". Remove the parentheses around the complete sentence.
There was a problem hiding this comment.
Nit: replace:
... a js file.
with:
... `*.js` files.
| 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 | ||
| `module.exports` and `exports` available in a js file, the details will be |
There was a problem hiding this comment.
", the details..." unnecessary, remove, or replace with a "see LINK" that links to the docs.
| module.exports.emit('ready'); | ||
| }, 1000); | ||
| ``` | ||
| There is no magic behind `exports`. It is the `module.exports` passed to |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
|
||
| As described in [module wrapper](#modules_the_module_wrapper), your js file |
There was a problem hiding this comment.
Please avoid the use of informal pronouns such as 'you', 'your', 'us', etc.
| }); | ||
| ``` | ||
| And this is a minimized logic of `require` for `module.exports`: | ||
| ```js |
There was a problem hiding this comment.
what is the purpose of this code snippet?
| above, and call it like the code logic described in `_require`. By the code | ||
| logic, behaviors of `module.exports` and `exports` are dependent on these | ||
| points: | ||
| - `require` is a synchronize process. |
There was a problem hiding this comment.
synchronize -> synchronous
| logic, behaviors of `module.exports` and `exports` are dependent on these | ||
| points: | ||
| - `require` is a synchronize process. | ||
| - `require` return the `module.exports` as the exports of a module. |
| points: | ||
| - `require` is a synchronize process. | ||
| - `require` return the `module.exports` as the exports of a module. | ||
| - Javascript always passes by value. |
There was a problem hiding this comment.
javascript always passes what by value?
|
|
||
| As a result, the export results of a module is a returned value of | ||
| `module.exports` at the tickcount which `require` is returned. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
// 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.
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.)
| done in any callbacks. This does not work: | ||
|
|
||
| x.js: | ||
| Let's illustrate the behaviors and principles with codes. (You can use either |
There was a problem hiding this comment.
@Trott is this colloquial "let's" and "you" used in node documentation?
"codes" -> "code"
| return module.exports; | ||
| } | ||
| ``` | ||
| When you `require` a file, Node.js will wrap it with a function wrapper as |
There was a problem hiding this comment.
I don't think this is a useful way to describe require. If you want to read the code to understand the behaviour, the code is there, its open source. Docs should describe behaviour and interface, not just reformat the code and expect the reader to read the code to figure out how it behaves.
There was a problem hiding this comment.
Indeed, this is me main purpose of the PR, cause of the old docs of module.export did not describe what the module.export should be and should not be, so this led to many people repeatedly ask what is a module.export and export in stackoverflow. previously if some one want to make sure what is a module.export, the only way is read the source code. Want to make this easier.
I thought _require is a pseudocode more than a code of reformating. Cause an exactly description maybe need hundreds of words(maybe will make the docs like a specification), so i thought a pseudocode is suitable here, and i checked it again, it is the things happened for module.export in currently source code.
The pseudocode make thes behaviors and interface of module.exports and exports obviously.
I think there should be an other alternatively good way to describe the behaviors and interface, but i am not be able to do that, cause of my poor English.
| module.exports = { a: 'hello' }; | ||
| }, 0); | ||
| ``` | ||
| function synchronize(exports, _, module) { // the module wrapper |
There was a problem hiding this comment.
this is not a useful way to describe how to write modules, since users do not actually write modules like this
| `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 | ||
| `this` as a shortcut for export. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Did do find this in old module docs. searched in doc/api/module.md again previously.
| `this` as a shortcut for export. | ||
|
|
||
| **As a guideline**, never use 'this' to export, and if the `exports` and | ||
| `module.exports` makes you confused, ignore `exports` and only use |
There was a problem hiding this comment.
if you are still confused at this point, the docs have failed. I don't see any description here about the real difference between the two:
exports is more brief to use, and is good when just exporting functions
module.exports is necessary to use when a module should return something other than the default object provided as an export value, such as a function
If you want to add guidelines, the guideline should be to redefine exports and module.exports at the same time:
module.exports = exports = MyConstructorFunction;
|
IMO, the attempt to demonstrate how the module system works by building a mini version of it is best left to a guide (or a blog post). |
|
@sam-github Thanks for you reviewing, it is my rough idea of making the But cause of my poor English( and also i am new to nodejs, there are many things i dont know), i has a lot of weird descriptions for my idea. After reading the reviewing, i have some thought: Cause of my poor English, not sure if i has ability to achieve 2 and 3. |
|
@iamchenxin If comfort writing in English is a problem for you, you could perhaps open an issue, describing what it was that you did not understand from the docs, and someone more comfortable in writing docs could then fix them for you, and you could review. Its a bit hard for me, I've found the docs clear, but if you didn't, then they need improving... but how specifically? |
Thinks happening in Honestly, I just re-read the docs, and they seem to describe this perfectly well: https://nodejs.org/api/modules.html#modules_module_exports Can you point to the stackoverflow questions? At this point, I'm -1 on this PR. It makes a number of things less clear, and doesn't appear to me to help with the actual problem. Would changing "alias" to "local variable" be more clear? |
|
@sam-github nope, it is not just for me, if you google what is |
|
You have only two semi-actionable comments right now:
Its hard to make improvements without more specific feedback. What exactly didn't you understand? |
|
about |
|
@sam-github I have the idea to improve the old doc when i try to mock functions exported from a module, and find there is not enough informations in docs for exports. exactly there is nothing im confusing now, cause of reading source code. ( The purpose is to make others do not need to ask questions for what is 2 And what about |
|
@sam-github Thanks for your patience to me. I make a lot of trouble to you. i move to #9622. |
|
Its my pleasure to help, if I can. |
Checklist
Affected core subsystem(s)
doc
Description of change
The module wrapper, themodule.exportscould be clearly explained with the logic of source code.thisto export values in a module file.babel-plugin, liketransform-es2015-modules-commonjswill breakthistoundefined, sincethisis undocumented, i thoughtbabel-pluginis free to break, and user should not use it.