backport: docs improvements

docs/general/welcome.md

@@ -25,7 +25,7 @@ v12 is still very much a work-in-progress, as we're aiming to make it the best i
 If you are fond of living life on the bleeding-edge, check out the master branch.
 
 ## About
-discord.js is a powerful [node.js](https://nodejs.org) module that allows you to interact with the
+discord.js is a powerful [Node.js](https://nodejs.org) module that allows you to interact with the
 [Discord API](https://discordapp.com/developers/docs/intro) very easily.
 
 - Object-oriented

src/client/Client.js

@@ -319,6 +319,10 @@ class Client extends EventEmitter {
    * Obtains an invite from Discord.
    * @param {InviteResolvable} invite Invite code or URL
    * @returns {Promise<Invite>}
+   * @example
+   * client.fetchInvite('https://discord.gg/bRCvFy9')
+   *   .then(invite => console.log(`Obtained invite with code: ${invite.code}`)
+   *   .catch(console.error);
    */
   fetchInvite(invite) {
     const code = this.resolver.resolveInviteCode(invite);
@@ -330,6 +334,10 @@ class Client extends EventEmitter {
    * @param {Snowflake} id ID of the webhook
    * @param {string} [token] Token for the webhook
    * @returns {Promise<Webhook>}
+   * @example
+   * client.fetchWebhook('id', 'token')
+   *   .then(webhook => console.log(`Obtained webhook with name: ${webhook.name}`))
+   *   .catch(console.error);
    */
   fetchWebhook(id, token) {
     return this.rest.methods.getWebhook(id, token);
@@ -338,6 +346,10 @@ class Client extends EventEmitter {
   /**
    * Obtains the available voice regions from Discord.
    * @returns {Collection<string, VoiceRegion>}
+   * @example
+   * client.fetchVoiceRegions()
+   *   .then(regions => console.log(`Available regions are: ${regions.map(region => region.name).join(', ')}`))
+   *   .catch(console.error);
    */
   fetchVoiceRegions() {
     return this.rest.methods.fetchVoiceRegions();
@@ -383,6 +395,9 @@ class Client extends EventEmitter {
    * Obtains the OAuth Application of the bot from Discord.
    * @param {Snowflake} [id='@me'] ID of application to fetch
    * @returns {Promise<OAuth2Application>}
+   * client.fetchApplication('id')
+   *   .then(application => console.log(`Obtained application with name: ${application.name}`)
+   *   .catch(console.error);
    */
   fetchApplication(id = '@me') {
     return this.rest.methods.getApplication(id);

src/sharding/Shard.js

@@ -70,9 +70,7 @@ class Shard {
    * @returns {Promise<*>}
    * @example
    * shard.fetchClientValue('guilds.size')
-   *   .then(count => {
+   *   .then(count => console.log(`${count} guilds in shard ${shard.id}`))
-   *     console.log(`${count} guilds in shard ${shard.id}`);
-   *   })
    *   .catch(console.error);
    */
   fetchClientValue(prop) {

src/structures/ClientUser.js

@@ -316,9 +316,7 @@ class ClientUser extends User {
    *   .catch(console.error);
    * @example
    * // Fetch mentions from a guild
-   * client.user.fetchMentions({
+   * client.user.fetchMentions({ guild: '222078108977594368' })
-   *   guild: '222078108977594368'
-   * })
    *   .then(console.log)
    *   .catch(console.error);
    */

src/structures/Invite.js

@@ -84,7 +84,7 @@ class Invite {
     if (data.inviter) {
       /**
        * The user who created this invite
-       * @type {User}
+       * @type {?User}
        */
       this.inviter = this.client.dataManager.newUser(data.inviter);
     }

src/structures/Role.js

@@ -284,6 +284,11 @@ class Role {
    * role.setPermissions(['KICK_MEMBERS', 'BAN_MEMBERS'])
    *   .then(updated => console.log(`Updated permissions to ${updated.permissions.bitfield}`))
    *   .catch(console.error);
+   * @example
+   * // Remove all permissions from a role
+   * role.setPermissions(0)
+   *   .then(updated => console.log(`Updated permissions to ${updated.permissions.bitfield}`))
+   *   .catch(console.error);
    */
   setPermissions(permissions, reason) {
     return this.edit({ permissions }, reason);

src/structures/TextChannel.js

@@ -52,6 +52,11 @@ class TextChannel extends GuildChannel {
   /**
    * Fetch all webhooks for the channel.
    * @returns {Promise<Collection<Snowflake, Webhook>>}
+   * @example
+   * // Fetch webhooks
+   * channel.fetchWebhooks()
+   *   .then(hooks => console.log(`This channel has ${hooks.size} hooks`))
+   *   .catch(console.error);
    */
   fetchWebhooks() {
     return this.client.rest.methods.getChannelWebhooks(this);

src/structures/interfaces/Collector.js

@@ -97,7 +97,7 @@ class Collector extends EventEmitter {
 
   /**
    * Return a promise that resolves with the next collected element;
-   * rejects with collected elements if the collector finishes without receving a next element
+   * rejects with collected elements if the collector finishes without receiving a next element
    * @type {Promise}
    * @readonly
    */