doc: punycode alternative name collision

[whymarrh]

📗 API Reference Docs Problem

• Version: v12.19.0 LTS

• Platform: Darwin x86_64

• Subsystem: punycode

Location

Section of the site where the content exists

Affected URL(s):

• https://nodejs.org/api/punycode.html#punycode_punycode
• https://nodejs.org/dist/latest-v12.x/docs/api/punycode.html#punycode_punycode

Description

Concise explanation of the problem

The punycode module docs note that it is deprecated and suggest using Punycode.js as an alternative:

The version of the punycode module bundled in Node.js is being deprecated.
In a future major version of Node.js this module will be removed. Users
currently depending on the punycode module should switch to using the
userland-provided Punycode.js module instead.

[…]

The punycode module is a third-party dependency used by Node.js and
made available to developers as a convenience. Fixes or other modifications to
the module must be directed to the Punycode.js project.

The alternative suggested is published as punycode on npm and thus its name is shadowed by the bundled version. A workaround is required to use the third-party module in place of the bundled module (see mathiasbynens/punycode.js#79 and mathiasbynens/punycode.js#113).

The API docs should either document the workaround required to use the suggested alternative, not suggest an alternative, or suggest an alternative that doesn't require a workaround.

---

• I would like to work on this issue and
  submit a pull request.

[jasnell]

The Punycode.js project readme already includes a good documentation notice about the workaround. I'm not convinced there's anything we really should do here.

[jasnell]

Closing given the above. We can reopen if there's more to discuss