doc: improve WHATWG url constructor code example

[lirantal]

Why this PR ?

Currently, the URL docs for the WHATWG URL spec support are
somewhat lacking in their code example of how to access the
new URL constructor that lives inside the core url package.

Suggested change

Improve the code example that shows how the new URL
constructor should be accessed to begin with.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[lirantal]

If we want to promote accessing the new WHATWG URL from the global scope then maybe the code example as-is is ok, but otherwise, since this is a docs for the core URL module then it is somewhat confusing how to access since doing this won't work:

const URL = require('url')
const myURL = new URL('..')

[addaleax]

@lirantal Yeah, since all supported Node.js versions have URL on the global object, I’d not document require('url').URL as the default way to access the URL constructor.

Maybe the Class: `URL` section could mention that this is an alternative way of accessing the class?

[lirantal]

Exactly, so it depends what we want to promote :-)
If we want to promote users to access URL via the global object that's probably good as is, though I'd even then add a comment to the code to make it clear. Since the docs are inside this core module and the other examples clearly shows the require for the url module, it makes this one where the change is due, somewhat ambiguous. Maybe it's just me.

[addaleax]

@lirantal Since nobody else has weighed in here yet: I’d say let’s not do this, and instead mention this as an alternative possibility for access in the URL constructor’s documentation section.

[lirantal]

Sure. So would we replace this one https://github.com/nodejs/node/pull/32782/files#diff-dd182d238def46a3af0d112f617e8838L104 with the option I suggested or just add it as a note below it? I need an actual code example would be good.

[jasnell]

Now that URL is global, this is not strictly required. This might be improved by explaining that distinction?

[lirantal]

I know it works global :)
I'm thinking out loud in this PR whether we want to promote that or not and yes to make one or the other more explicit so devs are aware.

[addaleax]

@lirantal I think an explicit second example would be good. E.g.:

The URL constructor is accessible as a property on the global object. It can also be imported from the built-in url module:

console.log(URL === require('url').URL); // Prints 'true'.

[lirantal]

@addaleax added it to the constructor example instead of the generic one on the intro.

[addaleax]

LGTM with the linter failure fixed (should be ```js)

[lirantal]

all fixed up 👍

[lirantal]

CI fails on Build from tarball / test-tarball-windows (pull_request) Failing after 51m — test-tarball-windows here: https://github.com/nodejs/node/actions/runs/87457793

[addaleax]

Landed in 6b2e3af

[lirantal]

Thanks Anna 👍