Move event jsdoc to respective classes. Document which functions fire.

This tends to boil down into a setXEvent method which can fire if it updates
the model.

lib/client.js

@@ -983,7 +983,6 @@ module.exports.MatrixClient = MatrixClient;
 
 // MatrixClient Event JSDocs
 
-// MatrixClient Events
 /**
  * Fires whenever the SDK receives a new event.
  * @event module:client~MatrixClient#"event"
@@ -993,6 +992,7 @@ module.exports.MatrixClient = MatrixClient;
  *   var sender = event.getSender();
  * });
  */
+
 /**
  * Fires whenever the SDK has a problem syncing.
  * @event module:client~MatrixClient#"syncError"
@@ -1003,92 +1003,6 @@ module.exports.MatrixClient = MatrixClient;
  * });
  */
 
-// Room Events
-/**
- * Fires whenever the timeline in a room is updated.
- * @event module:client~MatrixClient#"Room.timeline"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {Room} room The room whose Room.timeline was updated.
- * @param {boolean} toStartOfTimeline True if this event was added to the start
- * (beginning; oldest) of the timeline e.g. due to pagination.
- * @example
- * matrixClient.on("Room.timeline", function(event, room, toStartOfTimeline){
- *   if (toStartOfTimeline) {
- *     var messageToAppend = room.timeline[room.timeline.length - 1];
- *   }
- * });
- */
-/**
- * Fires whenever the name of a room is updated.
- * @event module:client~MatrixClient#"Room.name"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * This will not always be <code>m.room.name</code>, as sometimes
- * <code>m.room.aliases</code> or <code>m.room.member</code> events cause the
- * Room.name to be updated.
- * @param {Room} room The room whose Room.name was updated.
- * @example
- * matrixClient.on("Room.name", function(event, room){
- *   var newName = room.name;
- * });
- */
-
-// RoomState Events
-/**
- * Fires whenever the event dictionary in room state is updated.
- * @event module:client~MatrixClient#"RoomState.events"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {RoomState} state The room state whose RoomState.events dictionary
- * was updated.
- * @example
- * matrixClient.on("RoomState.events", function(event, state){
- *   var newStateEvent = event;
- * });
- */
-/**
- * Fires whenever the member dictionary in room state is updated.
- * @event module:client~MatrixClient#"RoomState.members"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {RoomState} state The room state whose RoomState.members dictionary
- * was updated.
- * @param {RoomMember} member The room member that was updated.
- * @example
- * matrixClient.on("RoomState.members", function(event, state, member){
- *   var newMembershipState = member.getMembershipState();
- * });
- */
-
-// User Events
-/**
- * Fires whenever any user's presence changes.
- * @event module:client~MatrixClient#"User.presence"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {User} user The user whose User.presence changed.
- * @example
- * matrixClient.on("User.presence", function(event, user){
- *   var newPresence = user.presence;
- * });
- */
-/**
- * Fires whenever any user's display name changes.
- * @event module:client~MatrixClient#"User.displayName"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {User} user The user whose User.displayName changed.
- * @example
- * matrixClient.on("User.displayName", function(event, user){
- *   var newName = user.displayName;
- * });
- */
-/**
- * Fires whenever any user's avatar URL changes.
- * @event module:client~MatrixClient#"User.avatarUrl"
- * @param {MatrixEvent} event The matrix event which caused this event to fire.
- * @param {User} user The user whose User.avatarUrl changed.
- * @example
- * matrixClient.on("User.avatarUrl", function(event, user){
- *   var newUrl = user.avatarUrl;
- * });
- */
-
 // EventEmitter JSDocs
 
 /**

lib/models/room-state.js

@@ -57,8 +57,12 @@ RoomState.prototype = {
 
     /**
      * Add an array of one or more state MatrixEvents, overwriting
-     * any existing state with the same {type, stateKey} tuple.
+     * any existing state with the same {type, stateKey} tuple. Will fire
+     * "RoomState.events" for every event added. May fire "RoomState.members"
+     * if there are <code>m.room.member</code> events.
      * @param {MatrixEvent[]} stateEvents a list of state events for this room.
+     * @fires module:client~MatrixClient#event:"RoomState.members"
+     * @fires module:client~MatrixClient#event:"RoomState.events"
      */
     setStateEvents: function(stateEvents) {
         var self = this;
@@ -105,3 +109,28 @@ RoomState.prototype = {
  * The RoomState class.
  */
 module.exports = RoomState;
+
+/**
+ * Fires whenever the event dictionary in room state is updated.
+ * @event module:client~MatrixClient#"RoomState.events"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {RoomState} state The room state whose RoomState.events dictionary
+ * was updated.
+ * @example
+ * matrixClient.on("RoomState.events", function(event, state){
+ *   var newStateEvent = event;
+ * });
+ */
+
+/**
+ * Fires whenever the member dictionary in room state is updated.
+ * @event module:client~MatrixClient#"RoomState.members"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {RoomState} state The room state whose RoomState.members dictionary
+ * was updated.
+ * @param {RoomMember} member The room member that was updated.
+ * @example
+ * matrixClient.on("RoomState.members", function(event, state, member){
+ *   var newMembershipState = member.getMembershipState();
+ * });
+ */

lib/models/room.js

@@ -43,11 +43,13 @@ Room.prototype = {
      },
 
     /**
-     * Add some events to this room's timeline.
+     * Add some events to this room's timeline. Will fire "Room.timeline" for
+     * each event added.
      * @param {MatrixEvent[]} events A list of events to add.
      * @param {boolean} toStartOfTimeline True to add these events to the start
      * (oldest) instead of the end (newest) of the timeline. If true, the oldest
      * event will be the <b>last</b> element of 'events'.
+     * @fires module:client~MatrixClient#event:"Room.timeline"
      */
     addEventsToTimeline: function(events, toStartOfTimeline) {
         for (var i = 0; i < events.length; i++) {
@@ -85,7 +87,9 @@ Room.prototype = {
     /**
      * Recalculate various aspects of the room, including the room name and
      * room summary. Call this any time the room's current state is modified.
+     * May fire "Room.name" if the room name is updated.
      * @param {string} userId The client's user ID.
+     * @fires module:client~MatrixClient#event:"Room.name"
      */
     recalculate: function(userId) {
         this.name = this.calculateRoomName(userId);
@@ -153,3 +157,32 @@ Room.prototype = {
  * The Room class.
  */
 module.exports = Room;
+
+/**
+ * Fires whenever the timeline in a room is updated.
+ * @event module:client~MatrixClient#"Room.timeline"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {Room} room The room whose Room.timeline was updated.
+ * @param {boolean} toStartOfTimeline True if this event was added to the start
+ * (beginning; oldest) of the timeline e.g. due to pagination.
+ * @example
+ * matrixClient.on("Room.timeline", function(event, room, toStartOfTimeline){
+ *   if (toStartOfTimeline) {
+ *     var messageToAppend = room.timeline[room.timeline.length - 1];
+ *   }
+ * });
+ */
+
+/**
+ * Fires whenever the name of a room is updated.
+ * @event module:client~MatrixClient#"Room.name"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * This will not always be <code>m.room.name</code>, as sometimes
+ * <code>m.room.aliases</code> or <code>m.room.member</code> events cause the
+ * Room.name to be updated.
+ * @param {Room} room The room whose Room.name was updated.
+ * @example
+ * matrixClient.on("Room.name", function(event, room){
+ *   var newName = room.name;
+ * });
+ */

lib/models/user.js

@@ -21,14 +21,63 @@ function User(userId, info) {
     this.userId = userId;
     this.info = info;
     if (info.presence) {
-        this.presence = info.presence.getContent().presence;
+        this.setPresenceEvent(info.presence);
-        this.displayName = info.presence.getContent().displayname;
-        this.avatarUrl = info.presence.getContent().avatar_url;
-        this.lastActiveAgo = info.presence.getContent().last_active_ago;
     }
 }
 
+/**
+ * Update this User with the given presence event. May fire "User.presence",
+ * "User.avatarUrl" and/or "User.displayName" if this event updates this user's
+ * properties.
+ * @param {MatrixEvent} event The <code>m.presence</code> event.
+ * @fires module:client~MatrixClient#event:"User.presence"
+ * @fires module:client~MatrixClient#event:"User.displayName"
+ * @fires module:client~MatrixClient#event:"User.avatarUrl"
+ */
+User.prototype.setPresenceEvent = function(event) {
+    if (event.getType() !== "m.presence") {
+        return;
+    }
+    this.presence = event.getContent().presence;
+    this.displayName = event.getContent().displayname;
+    this.avatarUrl = event.getContent().avatar_url;
+    this.lastActiveAgo = event.getContent().last_active_ago;
+};
+
 /**
  * The User class.
  */
 module.exports = User;
+
+/**
+ * Fires whenever any user's presence changes.
+ * @event module:client~MatrixClient#"User.presence"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {User} user The user whose User.presence changed.
+ * @example
+ * matrixClient.on("User.presence", function(event, user){
+ *   var newPresence = user.presence;
+ * });
+ */
+
+/**
+ * Fires whenever any user's display name changes.
+ * @event module:client~MatrixClient#"User.displayName"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {User} user The user whose User.displayName changed.
+ * @example
+ * matrixClient.on("User.displayName", function(event, user){
+ *   var newName = user.displayName;
+ * });
+ */
+
+/**
+ * Fires whenever any user's avatar URL changes.
+ * @event module:client~MatrixClient#"User.avatarUrl"
+ * @param {MatrixEvent} event The matrix event which caused this event to fire.
+ * @param {User} user The user whose User.avatarUrl changed.
+ * @example
+ * matrixClient.on("User.avatarUrl", function(event, user){
+ *   var newUrl = user.avatarUrl;
+ * });
+ */