Skip to content
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.

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

doc: improve WHATWG url constructor code example #32782

Closed
wants to merge 3 commits into from
Closed

doc: improve WHATWG url constructor code example #32782

wants to merge 3 commits into from

Conversation

lirantal
Copy link
Member

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

## 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.
@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to the documentations. url Issues and PRs related to the legacy built-in url module. labels Apr 11, 2020
@lirantal
Copy link
Member Author

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
Copy link
Member

@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
Copy link
Member Author

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
Copy link
Member

@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
Copy link
Member Author

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.

doc/api/url.md Outdated
@@ -53,6 +53,7 @@ WHATWG URL's `origin` property includes `protocol` and `host`, but not
Parsing the URL string using the WHATWG API:

```js
const URL = require('url').URL
Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Member Author

Choose a reason for hiding this comment

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

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
Copy link
Member

@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
Copy link
Member Author

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

Copy link
Member

@addaleax addaleax left a comment

Choose a reason for hiding this comment

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

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

@lirantal
Copy link
Member Author

all fixed up 👍

@lirantal
Copy link
Member Author

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 pushed a commit that referenced this pull request Apr 27, 2020
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.

PR-URL: #32782
Reviewed-By: Anna Henningsen <[email protected]>
@addaleax
Copy link
Member

Landed in 6b2e3af

@addaleax addaleax closed this Apr 27, 2020
@lirantal lirantal deleted the patch-1 branch April 28, 2020 06:56
@lirantal
Copy link
Member Author

Thanks Anna 👍

BethGriggs pushed a commit that referenced this pull request Apr 28, 2020
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.

PR-URL: #32782
Reviewed-By: Anna Henningsen <[email protected]>
BridgeAR pushed a commit that referenced this pull request Apr 28, 2020
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.

PR-URL: #32782
Reviewed-By: Anna Henningsen <[email protected]>
BridgeAR pushed a commit that referenced this pull request Apr 28, 2020
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.

PR-URL: #32782
Reviewed-By: Anna Henningsen <[email protected]>
@BridgeAR BridgeAR mentioned this pull request Apr 28, 2020
BethGriggs pushed a commit that referenced this pull request Apr 28, 2020
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.

PR-URL: #32782
Reviewed-By: Anna Henningsen <[email protected]>
@BethGriggs BethGriggs mentioned this pull request Apr 28, 2020
BethGriggs pushed a commit that referenced this pull request Apr 28, 2020
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.

PR-URL: #32782
Reviewed-By: Anna Henningsen <[email protected]>
targos pushed a commit that referenced this pull request Apr 30, 2020
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.

PR-URL: #32782
Reviewed-By: Anna Henningsen <[email protected]>
targos pushed a commit that referenced this pull request May 13, 2020
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.

PR-URL: #32782
Reviewed-By: Anna Henningsen <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. url Issues and PRs related to the legacy built-in url module.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants