Improving the documentation for `url.format()`

[zeke]

• Version: All
• Platform: All
• Subsystem: All

I've noticed that the documentation for the url.format() method has becoming a long-winded story of "If this condition is met, then this happens, else this other thing happens, unless something something."

I'm all for leaving this detailed explanation of the method's behavior intact, but I think it would also be immensely useful to have some example code to illustrate the common case. Something like this:

url.format({
  protocol: 'https',
  hostname: `en.wiktionary.org`,
  pathname: '/w/api.php',
  query: {
    action: 'query',
    format: 'json',
    prop: 'extracts',
    titles: 'orthogonal'
  }
})

I'm happy to open a pull request for this, but wanted to check first to see if a change like this would be welcomed.

[Trott]

Sounds good to me, although doc PRs do tend to attract a lot of comments/requests for changes. As long as you're prepared to be patient with the process, 👍!