From d2fcdd4556064d62b252af0bf9f4e7e776b5980f Mon Sep 17 00:00:00 2001
From: Kegan Dougal <kegan@matrix.org>
Date: Wed, 10 Jun 2015 13:02:32 +0100
Subject: [PATCH] Add jsdoc for EventEmitter.

---
 lib/client.js | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/lib/client.js b/lib/client.js
index 05ebf3e29..a9694b0e9 100644
--- a/lib/client.js
+++ b/lib/client.js
@@ -18,6 +18,7 @@ var utils = require("./utils");
 /**
  * Construct a Matrix Client.
  * @constructor
+ * @extends external:EventEmitter
  * @param {Object} opts The configuration options for this client.
  * @param {string} opts.baseUrl Required. The base URL to the client-server HTTP API.
  * @param {Function} opts.request Required. The function to invoke for HTTP requests.
@@ -53,6 +54,7 @@ function MatrixClient(opts) {
     this._http = new httpApi.MatrixHttpApi(httpOpts);
 }
 // inherit from EventEmitter (not with ECMA5 Object.prototype for compat with IE8)
+// See MDN for this shim impl.
 function createObject(proto) {
     function Ctor() { }
     Ctor.prototype = proto;
@@ -423,6 +425,7 @@ MatrixClient.prototype.kick = function(roomId, userId, reason, callback) {
 };
 
 /**
+ * This is an internal method.
  * @param {MatrixClient} client
  * @param {string} roomId
  * @param {string} userId
@@ -448,6 +451,7 @@ function _setMembershipState(client, roomId, userId, membershipValue, reason,
 }
 
 /**
+ * This is an internal method.
  * @param {MatrixClient} client
  * @param {string} roomId
  * @param {string} userId
@@ -900,6 +904,7 @@ MatrixClient.prototype.startClient = function(callback, historyLen) {
 };
 
 /**
+ * This is an internal method.
  * @param {MatrixClient} client
  * @param {module:client.callback} callback Optional.
  */
@@ -973,6 +978,81 @@ MatrixClient.prototype.stopClient = function() {
 /** */
 module.exports.MatrixClient = MatrixClient;
 
+// EventEmitter JSDocs
+
+/**
+ * The {@link https://nodejs.org/api/events.html|EventEmitter} class.
+ * @external EventEmitter
+ * @see {@link https://nodejs.org/api/events.html}
+ */
+
+/**
+ * Adds a listener to the end of the listeners array for the specified event.
+ * No checks are made to see if the listener has already been added. Multiple
+ * calls passing the same combination of event and listener will result in the
+ * listener being added multiple times.
+ * @function external:EventEmitter#on
+ * @param {string} event The event to listen for.
+ * @param {Function} listener The function to invoke.
+ * @return {EventEmitter} for call chaining.
+ */
+
+/**
+ * Alias for {@link external:EventEmitter#on}.
+ * @function external:EventEmitter#addListener
+ * @param {string} event The event to listen for.
+ * @param {Function} listener The function to invoke.
+ * @return {EventEmitter} for call chaining.
+ */
+
+/**
+ * Adds a <b>one time</b> listener for the event. This listener is invoked only
+ * the next time the event is fired, after which it is removed.
+ * @function external:EventEmitter#once
+ * @param {string} event The event to listen for.
+ * @param {Function} listener The function to invoke.
+ * @return {EventEmitter} for call chaining.
+ */
+
+/**
+ * Remove a listener from the listener array for the specified event.
+ * <b>Caution:</b> changes array indices in the listener array behind the
+ * listener.
+ * @function external:EventEmitter#removeListener
+ * @param {string} event The event to listen for.
+ * @param {Function} listener The function to invoke.
+ * @return {EventEmitter} for call chaining.
+ */
+
+/**
+ * Removes all listeners, or those of the specified event. It's not a good idea
+ * to remove listeners that were added elsewhere in the code, especially when
+ * it's on an emitter that you didn't create (e.g. sockets or file streams).
+ * @function external:EventEmitter#removeAllListeners
+ * @param {string} event Optional. The event to remove listeners for.
+ * @return {EventEmitter} for call chaining.
+ */
+
+/**
+ * Execute each of the listeners in order with the supplied arguments.
+ * @function external:EventEmitter#emit
+ * @param {string} event The event to emit.
+ * @param {Function} listener The function to invoke.
+ * @return {boolean} true if event had listeners, false otherwise.
+ */
+
+/**
+ * By default EventEmitters will print a warning if more than 10 listeners are
+ * added for a particular event. This is a useful default which helps finding
+ * memory leaks. Obviously not all Emitters should be limited to 10. This
+ * function allows that to be increased. Set to zero for unlimited.
+ * @function external:EventEmitter#setMaxListeners
+ * @param {Number} n The max number of listeners.
+ * @return {EventEmitter} for call chaining.
+ */
+
+// MatrixClient Callback JSDocs
+
 /**
  * The standard MatrixClient callback interface. Functions which accept this
  * will specify 2 return arguments. These arguments map to the 2 parameters