From 35c4c552f49516f166729bd8de909fc08fb7a9a2 Mon Sep 17 00:00:00 2001
From: Will Nelson <nelson.will@live.com>
Date: Fri, 28 Apr 2017 10:45:46 -0700
Subject: [PATCH] [wip] Fix collector documentation (again) (#1416)

* remove private on abstract methods, fix timeout type

* make client readonly, add documentation to abstract methods

* document implemented collector methods
---
 src/structures/MessageCollector.js     | 15 +++++++++++++++
 src/structures/ReactionCollector.js    | 17 +++++++++++++++++
 src/structures/interfaces/Collector.js | 15 +++++++++------
 3 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/src/structures/MessageCollector.js b/src/structures/MessageCollector.js
index 34bc6b3cc..8e96187cf 100644
--- a/src/structures/MessageCollector.js
+++ b/src/structures/MessageCollector.js
@@ -50,6 +50,12 @@ class MessageCollector extends Collector {
     this.on('collect', this._reEmitter);
   }
 
+  /**
+   * Handle an incoming message for possible collection.
+   * @param {Message} message The message that could be collected.
+   * @returns {?{key: Snowflake, value: Message}} Message data to collect.
+   * @private
+   */
   handle(message) {
     if (message.channel.id !== this.channel.id) return null;
     this.received++;
@@ -59,6 +65,11 @@ class MessageCollector extends Collector {
     };
   }
 
+  /**
+   * Check after collection to see if the collector is done.
+   * @returns {?string} Reason to end the collector, if any.
+   * @private
+   */
   postCheck() {
     // Consider changing the end reasons for v12
     if (this.options.maxMatches && this.collected.size >= this.options.max) return 'matchesLimit';
@@ -66,6 +77,10 @@ class MessageCollector extends Collector {
     return null;
   }
 
+  /**
+   * Removes event listeners.
+   * @private
+   */
   cleanup() {
     this.removeListener('collect', this._reEmitter);
     this.client.removeListener('message', this.listener);
diff --git a/src/structures/ReactionCollector.js b/src/structures/ReactionCollector.js
index 44b38c685..555ecf1ca 100644
--- a/src/structures/ReactionCollector.js
+++ b/src/structures/ReactionCollector.js
@@ -43,6 +43,12 @@ class ReactionCollector extends Collector {
     this.client.on('messageReactionAdd', this.listener);
   }
 
+  /**
+   * Handle an incoming reaction for possible collection.
+   * @param {MessageReaction} reaction The reaction to possibly collect.
+   * @returns {?{key: Snowflake, value: MessageReaction}} Reaction data to collect.
+   * @private
+   */
   handle(reaction) {
     if (reaction.message.id !== this.message.id) return null;
     return {
@@ -51,6 +57,13 @@ class ReactionCollector extends Collector {
     };
   }
 
+  /**
+   * Check after collection to see if the collector is done.
+   * @param {MessageReaction} reaction The reaction that was collected.
+   * @param {User} user The user that reacted.
+   * @returns {?string} Reason to end the collector, if any.
+   * @private
+   */
   postCheck(reaction, user) {
     this.users.set(user.id, user);
     if (this.options.max && ++this.total >= this.options.max) return 'limit';
@@ -59,6 +72,10 @@ class ReactionCollector extends Collector {
     return null;
   }
 
+  /**
+   * Remove event listeners.
+   * @private
+   */
   cleanup() {
     this.client.removeListener('messageReactionAdd', this.listener);
   }
diff --git a/src/structures/interfaces/Collector.js b/src/structures/interfaces/Collector.js
index e43706c92..66c0711e6 100644
--- a/src/structures/interfaces/Collector.js
+++ b/src/structures/interfaces/Collector.js
@@ -24,9 +24,11 @@ class Collector extends EventEmitter {
 
     /**
      * The client.
+     * @name Collector#client
      * @type {Client}
+     * @readonly
      */
-    this.client = client;
+    Object.defineProperty(this, 'client', { value: client });
 
     /**
      * The filter applied to this collector.
@@ -53,8 +55,8 @@ class Collector extends EventEmitter {
     this.ended = false;
 
     /**
-     * Timeout ID for cleanup.
-     * @type {?number}
+     * Timeout for cleanup.
+     * @type {?Timeout}
      * @private
      */
     this._timeout = null;
@@ -148,25 +150,26 @@ class Collector extends EventEmitter {
 
   /* eslint-disable no-empty-function, valid-jsdoc */
   /**
+   * Handles incoming events from the `listener` function.  Returns null if the
+   * event should not be collected, or returns an object describing the data that should be stored.
+   * @see Collector#listener
    * @param {...*} args Any args the event listener emits.
    * @returns {?{key: string, value}} Data to insert into collection, if any.
    * @abstract
-   * @private
    */
   handle() {}
 
   /**
+   * This method runs after collection to see if the collector should finish.
    * @param {...*} args Any args the event listener emits.
    * @returns {?string} Reason to end the collector, if any.
    * @abstract
-   * @private
    */
   postCheck() {}
 
   /**
    * Called when the collector is ending.
    * @abstract
-   * @private
    */
   cleanup() {}
   /* eslint-enable no-empty-function, valid-jsdoc */