Repository navigation
doc: missing require calls in some code examples #6596
Description
Hi,
wandering through the api docs, I recognized that some code examples do
not have a const foo = require('foo'); in it, but just use foo without requiring it.
Obviously when we talk about global modules like Buffer or process this is totally correct.
However some require calls are really missing, among others, in e.g. net module or querystring module.
I would like to create a PR for it, adding the missing require calls.
In this context, I would also like to mention the PR about introducing ESLint for the docs, where this ESLint rule seems to be a good fit for this issue.
Do you guys have any thoughts or proposals for this issue before I dive in?
Thanks for your feedback. 😉
Activity
Trott commentedon May 27, 2017
Feel free to open a pull request for any sample code that is missing a non-obvious
require()call. (As you suggest, I don't think we need to addconst buffer = require('buffer')to every example in thebufferdocs, but if sample code in there also usesassert, then adding arequire()forasserttotally makes sense to me.)/cc @nodejs/documentation especially @vsemozhetbyt who may have already fixed this?
vsemozhetbyt commentedon May 27, 2017
@Trott As I recall, we have a huge amount of omissions here, and this is partly the cause the
no-undefrule is off in the doc/.eslintrc.yaml. I also recall some of the collaborators told the docs examples need not be a full runnable code, they imply a lot of prerequisites and omissions ofrequire()are included in this implying.Trott commentedon May 27, 2017
In that case, should we close this issue?
vsemozhetbyt commentedon May 27, 2017
If nobody has an objection, maybe we could.
Trott commentedon May 27, 2017
Closing, but if anyone (including original poster) thinks that's misguided, feel free to comment (or re-open if GitHub permits you to).
janriemer commentedon May 28, 2017
Hi guys,
thanks for your engagement in this issue.
I've seen that e.g. in Query String module there is now a dedicated section showing how to access this module with
require, so this issue has become obsolete and can remain closed.Just in case you want to know, why I'm so picky about this (feel free to ignore this): 😉
It is important to me that we are always explicit in the docs, so that there are no open questions about basic usage of a module.
E.g. just look at the Child Process module:
it is
require('child_process')and not e.g.require('childprocess')(w/o '_')When we now look at the Query String module, it wouldn't be obvious how to require it:
is it
require('query_string')orrequire('querystring')?