From 07f77c495b197c86451ec950ecaeccf30a752cda Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Thu, 11 Jun 2015 10:54:25 +0100 Subject: [PATCH] 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 | 88 +--------------------------------------- lib/models/room-state.js | 31 +++++++++++++- lib/models/room.js | 35 +++++++++++++++- lib/models/user.js | 57 ++++++++++++++++++++++++-- 4 files changed, 118 insertions(+), 93 deletions(-) diff --git a/lib/client.js b/lib/client.js index 0ff70bbd5..1303e7cbf 100644 --- a/lib/client.js +++ b/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 m.room.name, as sometimes - * m.room.aliases or m.room.member 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 /** diff --git a/lib/models/room-state.js b/lib/models/room-state.js index 951a46877..49309c883 100644 --- a/lib/models/room-state.js +++ b/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 m.room.member 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(); + * }); + */ diff --git a/lib/models/room.js b/lib/models/room.js index b685d969c..d77e4f434 100644 --- a/lib/models/room.js +++ b/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 last 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 m.room.name, as sometimes + * m.room.aliases or m.room.member 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; + * }); + */ diff --git a/lib/models/user.js b/lib/models/user.js index b8206eb0a..47934fda3 100644 --- a/lib/models/user.js +++ b/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.displayName = info.presence.getContent().displayname; - this.avatarUrl = info.presence.getContent().avatar_url; - this.lastActiveAgo = info.presence.getContent().last_active_ago; + this.setPresenceEvent(info.presence); } } +/** + * 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 m.presence 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; + * }); + */