doc: add how to access URL constructor

[tim-phillips]

It was unclear to me how to access the constructor. This should clear things up for future users.

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[addaleax]

It might be worth explicitly mentioning that this only applies up to Node 8, since Node 10 it’s also accessibly as a global?

[Trott]

It might be worth explicitly mentioning that this only applies up to Node 8, since Node 10 it’s also accessibly as a global?

In that case, should this PR target v8.x-staging rather than master?

[Trott]

In that case, should this PR target v8.x-staging rather than master?

The v8.x docs include the const { URL } = require('url'); in the relevant example. See https://nodejs.org/dist/latest-v8.x/docs/api/url.html#url_url_strings_and_url_objects.

So I think this PR may be unnecessary? (Or maybe there's an issue where it's not sufficiently clear what version of the docs one is reading on the website?)

[tim-phillips]

I didn’t realize it was global, even though it does mention it in the doc. I was looking specifically for an import statement.

Would it be against convention to add /* global: URL */ to the first example? Or is there a convention to mark things as global in the docs?

[richardlau]

FWIW the const { URL } = require('url'); was removed by #20364.

[TimothyGu]

BTW the v8.x docs have const { URL } = require('url'); in all of its examples.

[Trott]

Would it be against convention to add /* global: URL */ to the first example? Or is there a convention to mark things as global in the docs?

I don't think we do that anywhere else, but that doesn't mean we can't in this situation or start a general practice along those lines. /pinging @nodejs/documentation @nodejs/website for thoughts

[devsnek]

i thought the current practice was to treat the examples as runnable code yea? so if they reference something without require/etc it should be assumed to be a global.

[vsemozhetbyt]

i thought the current practice was to treat the examples as runnable code yea?

FWIW, we still have this point in the STYLE_GUIDE:

Code need not be complete — treat code blocks as an illustration or aid to your point, not as complete running programs. If a complete running program is necessary, include it as an asset in assets/code-examples and link to it.

And we still have many examples with assumed require().

[addaleax]

Given the above comments, I’m closing this.

If you think this should be re-opened, please let us know and we’ll be happy to do so!