From 1db09064831e4bf040d0fcd867c2ac3c35aca127 Mon Sep 17 00:00:00 2001
From: Artful <kye.normangill@tafensw.net.au>
Date: Thu, 18 Jan 2018 17:47:05 +1100
Subject: [PATCH] Client method examples. (#2264)

* Client method examples.

* Consistency

* As per hydras request :bow:

* Thanks kya
---
 src/client/Client.js | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/src/client/Client.js b/src/client/Client.js
index 77f0682c2..b16d20eed 100644
--- a/src/client/Client.js
+++ b/src/client/Client.js
@@ -287,6 +287,11 @@ class Client extends BaseClient {
    * 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 = DataResolver.resolveInviteCode(invite);
@@ -299,6 +304,11 @@ class Client extends BaseClient {
    * @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.api.webhooks(id, token).get().then(data => new Webhook(this, data));
@@ -307,6 +317,11 @@ class Client extends BaseClient {
   /**
    * 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.api.voice.regions.get().then(res => {
@@ -323,6 +338,10 @@ class Client extends BaseClient {
    * will be removed from the caches. The default is based on {@link ClientOptions#messageCacheLifetime}
    * @returns {number} Amount of messages that were removed from the caches,
    * or -1 if the message cache lifetime is unlimited
+   * @example
+   * // Remove all messages older than 1800 seconds from the messages cache
+   * const amount = client.sweepMessages(1800);
+   * console.log(`Successfully removed ${amount} messages from the cache.`);
    */
   sweepMessages(lifetime = this.options.messageCacheLifetime) {
     if (typeof lifetime !== 'number' || isNaN(lifetime)) {
@@ -359,6 +378,11 @@ class Client extends BaseClient {
    * Obtains the OAuth Application of the bot from Discord.
    * @param {Snowflake} [id='@me'] ID of application to fetch
    * @returns {Promise<ClientApplication>}
+   * @example
+   * client.fetchApplication('id')
+   *  .then(application => {
+   *    console.log(`Obtained application with name: ${application.name}`);
+   *  }).catch(console.error);
    */
   fetchApplication(id = '@me') {
     return this.api.oauth2.applications(id).get()
@@ -374,7 +398,7 @@ class Client extends BaseClient {
    * client.generateInvite(['SEND_MESSAGES', 'MANAGE_GUILD', 'MENTION_EVERYONE'])
    *   .then(link => {
    *     console.log(`Generated bot invite link: ${link}`);
-   *   });
+   *   }).catch(console.error);
    */
   generateInvite(permissions) {
     if (permissions) {