Document fired events with JSDoc

src/converse-bookmarks.js

@@ -545,6 +545,16 @@ converse.plugins.add('converse-bookmarks', {
                 _converse.bookmarksview = new _converse.BookmarksView({'model': _converse.bookmarks});
                 await _converse.bookmarks.fetchBookmarks();
             }
+            /**
+             * Triggered once the _converse.Bookmarks collection and _converse.BookmarksView view
+             * has been created and cached bookmarks have been fetched.
+             *
+             * Also gets emitted if it was determined that the server doesn't
+             * have sufficient support for PEP-based bookmarks (in which case
+             * the above two instances don't get created).
+             * @event _converse#bookmarksInitialized
+             * @example _converse.api.listen.on('bookmarksInitialized', () => { ... });
+             */
             _converse.api.emit('bookmarksInitialized');
         }
 

src/converse-chatboxviews.js

@@ -168,6 +168,11 @@ converse.plugins.add('converse-chatboxviews', {
             _converse.chatboxviews = new _converse.ChatBoxViews({
                 'model': _converse.chatboxes
             });
+            /**
+             * Triggered once the _converse.ChatBoxViews view-colleciton has been initialized
+             * @event _converse#chatBoxViewsInitialized
+             * @example _converse.api.listen.on('chatBoxViewsInitialized', () => { ... });
+             */
             _converse.api.emit('chatBoxViewsInitialized');
         });
 

src/converse-chatview.js

@@ -180,6 +180,14 @@ converse.plugins.add('converse-chatview', {
 
             onStatusMessageChanged (item) {
                 this.render();
+                /**
+                 * When a contact's custom status message has changed.
+                 * @event _converse#contactStatusMessageChanged
+                 * @type {object}
+                 * @property { object } contact - The chat buddy
+                 * @property { string } message - The message text
+                 * @example _converse.api.listen.on('contactStatusMessageChanged', obj => { ... });
+                 */
                 _converse.api.emit('contactStatusMessageChanged', {
                     'contact': item.attributes,
                     'message': item.get('status')
@@ -201,6 +209,12 @@ converse.plugins.add('converse-chatview', {
                 this.model.on('contactAdded', this.registerContactEventHandlers, this);
                 this.model.on('change', this.render, this);
                 this.registerContactEventHandlers();
+                /**
+                 * Triggered once the _converse.UserDetailsModal has been initialized
+                 * @event _converse#userDetailsModalInitialized
+                 * @type { _converse.ChatBox }
+                 * @example _converse.api.listen.on('userDetailsModalInitialized', chatbox => { ... });
+                 */
                 _converse.api.emit('userDetailsModalInitialized', this.model);
             },
 
@@ -275,6 +289,13 @@ converse.plugins.add('converse-chatview', {
         });
 
 
+        /**
+         * The View of an open/ongoing chat conversation.
+         *
+         * @class
+         * @namespace _converse.ChatBoxView
+         * @memberOf _converse
+         */
         _converse.ChatBoxView = Backbone.NativeView.extend({
             length: 200,
             className: 'chatbox hidden',
@@ -315,7 +336,13 @@ converse.plugins.add('converse-chatview', {
                 this.render();
 
                 this.fetchMessages();
-                _converse.api.emit('chatBoxOpened', this);
+                _converse.api.emit('chatBoxOpened', this); // TODO: remove
+                /**
+                 * Triggered once the _converse.ChatBoxView has been initialized
+                 * @event _converse#chatBoxInitialized
+                 * @type { _converse.ChatBoxView | _converse.HeadlinesBoxView }
+                 * @example _converse.api.listen.on('chatBoxInitialized', view => { ... });
+                 */
                 _converse.api.emit('chatBoxInitialized', this);
             },
 
@@ -351,6 +378,12 @@ converse.plugins.add('converse-chatview', {
                 this.el.querySelector('.chat-toolbar').innerHTML = toolbar(options);
                 this.addSpoilerButton(options);
                 this.addFileUploadButton();
+                /**
+                 * Triggered once the _converse.ChatBoxView's toolbar has been rendered
+                 * @event _converse#renderToolbar
+                 * @type { _converse.ChatBoxView }
+                 * @example _converse.api.listen.on('renderToolbar', view => { ... });
+                 */
                 _converse.api.emit('renderToolbar', this);
                 return this;
             },
@@ -485,6 +518,13 @@ converse.plugins.add('converse-chatview', {
                 this.insertIntoDOM();
                 this.scrollDown();
                 this.content.addEventListener('scroll', this.markScrolled.bind(this));
+                /**
+                 * Triggered whenever a `_converse.ChatBox` instance has fetched its messages from
+                 * `sessionStorage` but **NOT** from the server.
+                 * @event _converse#afterMessagesFetched 
+                 * @type {_converse.ChatBoxView | _converse.ChatRoomView}
+                 * @example _converse.api.listen.on('afterMessagesFetched', view => { ... });
+                 */
                 _converse.api.emit('afterMessagesFetched', this);
             },
 
@@ -792,6 +832,14 @@ converse.plugins.add('converse-chatview', {
                 if (message.get('correcting')) {
                     this.insertIntoTextArea(message.get('message'), true, true);
                 }
+                /**
+                 * Triggered once a message has been added to a chatbox.
+                 * @event _converse#messageAdded
+                 * @type {object}
+                 * @property { _converse.Message } message - The message instance
+                 * @property { _converse.ChatBox | _converse.ChatRoom } chatbox - The chat model
+                 * @example _converse.api.listen.on('messageAdded', data => { ... });
+                 */
                 _converse.api.emit('messageAdded', {
                     'message': message,
                     'chatbox': this.model
@@ -878,6 +926,12 @@ converse.plugins.add('converse-chatview', {
                     textarea.value = '';
                     u.removeClass('correcting', textarea);
                     textarea.style.height = 'auto'; // Fixes weirdness
+                    /**
+                     * Triggered just before an HTML5 message notification will be sent out.
+                     * @event _converse#messageSend
+                     * @type { _converse.Message }
+                     * @example _converse.api.listen.on('messageSend', data => { ... });
+                     */
                     _converse.api.emit('messageSend', message);
                 }
                 textarea.removeAttribute('disabled');
@@ -1081,6 +1135,14 @@ converse.plugins.add('converse-chatview', {
 
             toggleCall (ev) {
                 ev.stopPropagation();
+                /**
+                 * When a call button (i.e. with class .toggle-call) on a chatbox has been clicked.
+                 * @event _converse#callButtonClicked
+                 * @type { object }
+                 * @property { Strophe.Connection } _converse.connection - The XMPP Connection object
+                 * @property { _converse.ChatBox | _converse.ChatRoom } _converse.connection - The XMPP Connection object
+                 * @example _converse.api.listen.on('callButtonClicked', (connection, model) => { ... });
+                 */
                 _converse.api.emit('callButtonClicked', {
                     connection: _converse.connection,
                     model: this.model
@@ -1162,6 +1224,12 @@ converse.plugins.add('converse-chatview', {
                     _converse.log(e, Strophe.LogLevel.ERROR);
                 }
                 this.remove();
+                /**
+                 * Triggered once a chatbox has been closed.
+                 * @event _converse#chatBoxClosed
+                 * @type { _converse.ChatBoxView | _converse.ChatRoomView }
+                 * @example _converse.api.listen.on('chatBoxClosed', view => { ... });
+                 */
                 _converse.api.emit('chatBoxClosed', this);
                 return this;
             },
@@ -1182,6 +1250,12 @@ converse.plugins.add('converse-chatview', {
                 const textarea_el = this.el.querySelector('.chat-textarea');
                 if (!_.isNull(textarea_el)) {
                     textarea_el.focus();
+                    /**
+                     * Triggered when the focus has been moved to a particular chat.
+                     * @event _converse#chatBoxFocused
+                     * @type { _converse.ChatBoxView | _converse.ChatRoomView }
+                     * @example _converse.api.listen.on('chatBoxFocused', view => { ... });
+                     */
                     _converse.api.emit('chatBoxFocused', this);
                 }
                 return this;
@@ -1265,7 +1339,14 @@ converse.plugins.add('converse-chatview', {
                 if (_converse.windowState !== 'hidden') {
                     this.model.clearUnreadMsgCounter();
                 }
-                _converse.api.emit('chatBoxScrolledDown', {'chatbox': this.model});
+                /**
+                 * Triggered once the chat's message area has been scrolled down to the bottom.
+                 * @event _converse#chatBoxScrolledDown
+                 * @type {object}
+                 * @property { _converse.ChatBox | _converse.ChatRoom } chatbox - The chat model
+                 * @example _converse.api.listen.on('chatBoxScrolledDown', obj => { ... });
+                 */
+                _converse.api.emit('chatBoxScrolledDown', {'chatbox': this.model}); // TODO: clean up
             },
 
             onWindowStateChanged (state) {

src/converse-controlbox.js

@@ -224,6 +224,14 @@ converse.plugins.add('converse-controlbox', {
                 if (this.model.get('connected')) {
                     this.insertRoster();
                 }
+                /**
+                 * Triggered when the _converse.ControlBoxView has been initialized and therefore
+                 * exists. The controlbox contains the login and register forms when the user is
+                 * logged out and a list of the user's contacts and group chats when logged in.
+                 * @event _converse#chatBoxInitialized
+                 * @type { _converse.ControlBoxView }
+                 * @example _converse.api.listen.on('controlboxInitialized', view => { ... });
+                 */
                 _converse.api.emit('controlboxInitialized', this);
             },
 

src/converse-headline.js

@@ -81,7 +81,7 @@ converse.plugins.add('converse-headline', {
                 this.model.on('change:minimized', this.onMinimizedChanged, this);
 
                 this.render().insertHeading().fetchMessages().insertIntoDOM().hide();
-                _converse.api.emit('chatBoxOpened', this);
+                _converse.api.emit('chatBoxOpened', this); // TODO: remove
                 _converse.api.emit('chatBoxInitialized', this);
             },
 

src/converse-minimize.js

@@ -131,7 +131,13 @@ converse.plugins.add('converse-minimize', {
                     this.model.clearUnreadMsgCounter();
                 }
                 this.show();
-                this.__super__._converse.api.emit('chatBoxMaximized', this);
+                /**
+                 * Triggered when a previously minimized chat gets maximized
+                 * @event _converse#chatBoxMaximized
+                 * @type { _converse.ChatBoxView }
+                 * @example _converse.api.listen.on('chatBoxMaximized', view => { ... });
+                 */
+                _converse.api.emit('chatBoxMaximized', this);
                 return this;
             },
 
@@ -146,6 +152,12 @@ converse.plugins.add('converse-minimize', {
                 }
                 this.setChatState(_converse.INACTIVE).model.minimize();
                 this.hide();
+                /**
+                 * Triggered when a previously maximized chat gets Minimized
+                 * @event _converse#chatBoxMinimized
+                 * @type { _converse.ChatBoxView }
+                 * @example _converse.api.listen.on('chatBoxMinimized', view => { ... });
+                 */
                 _converse.api.emit('chatBoxMinimized', this);
             },
         },
@@ -388,6 +400,12 @@ converse.plugins.add('converse-minimize', {
                 this.model.on("destroy", this.removeChat, this);
                 this.model.on("change:minimized", this.onChanged, this);
                 this.model.on('change:num_unread', this.updateUnreadMessagesCounter, this);
+                /**
+                 * Triggered once the _converse.MinimizedChats instance has been * initialized
+                 * @event _converse#minimizedChatsInitialized
+                 * @example _converse.api.listen.on('minimizedChatsInitialized', () => { ... });
+                 */
+                _converse.api.emit('minimizedChatsInitialized');
             },
 
             render () {
@@ -515,7 +533,6 @@ converse.plugins.add('converse-minimize', {
             _converse.minimized_chats = new _converse.MinimizedChats({
                 model: _converse.chatboxes
             });
-            _converse.api.emit('minimizedChatsInitialized');
         }).catch(_.partial(_converse.log, _, Strophe.LogLevel.FATAL));
 
 

src/converse-muc-views.js

@@ -76,6 +76,12 @@ converse.plugins.add('converse-muc-views', {
                 this.el.querySelector('.controlbox-pane').insertAdjacentElement(
                     'beforeEnd', this.roomspanel.render().el);
 
+                /**
+                 * Triggered once the section of the _converse.ControlBoxView
+                 * which shows gropuchats has been rendered.
+                 * @event _converse#roomsPanelRendered
+                 * @example _converse.api.listen.on('roomsPanelRendered', () => { ... });
+                 */
                 _converse.api.emit('roomsPanelRendered');
             },
 
@@ -488,6 +494,13 @@ converse.plugins.add('converse-muc-views', {
         });
 
 
+        /**
+         * The View of an open/ongoing groupchat conversation
+         *
+         * @class
+         * @namespace _converse.ChatRoomView
+         * @memberOf _converse
+         */
         _converse.ChatRoomView = _converse.ChatBoxView.extend({
             /* Backbone.NativeView which renders a groupchat, based upon the view
              * for normal one-on-one chat boxes.
@@ -561,6 +574,12 @@ converse.plugins.add('converse-muc-views', {
                 } else {
                     this.fetchMessages();
                 }
+                /**
+                 * Triggered once a groupchat has been opened
+                 * @event _converse#chatRoomOpened
+                 * @type { _converse.ChatRoomView }
+                 * @example _converse.api.listen.on('chatRoomOpened', view => { ... });
+                 */
                 _converse.api.emit('chatRoomOpened', this);
             },
 

src/converse-notification.js

@@ -260,6 +260,13 @@ converse.plugins.add('converse-notification', {
             if (!_converse.shouldNotifyOfMessage(message)) {
                 return false;
             }
+            /**
+             * Triggered when a notification (sound or HTML5 notification) for a new
+             * message has will be made.
+             * @event _converse#messageNotification
+             * @type { XMLElement }
+             * @example _converse.api.listen.on('messageNotification', stanza => { ... });
+             */
             _converse.api.emit('messageNotification', message);
             _converse.playSoundNotification();
             _converse.showMessageNotification(message);

src/converse-omemo.js

@@ -1132,6 +1132,11 @@ converse.plugins.add('converse-omemo', {
             await fetchOwnDevices();
             await restoreOMEMOSession();
             await _converse.omemo_store.publishBundle();
+            /**
+             * Triggered once OMEMO support has been initialized
+             * @event _converse#OMEMOInitialized
+             * @example _converse.api.listen.on('OMEMOInitialized', () => { ... });
+             */
             _converse.api.emit('OMEMOInitialized');
         }
 

src/converse-profile.js

@@ -48,6 +48,12 @@ converse.plugins.add('converse-profile', {
             initialize () {
                 this.model.on('change', this.render, this);
                 _converse.BootstrapModal.prototype.initialize.apply(this, arguments);
+                /**
+                 * Triggered when the _converse.ProfileModal has been created and initialized.
+                 * @event _converse#profileModalInitialized
+                 * @type { _converse.XMPPStatus }
+                 * @example _converse.api.listen.on('profileModalInitialized', status => { ... });
+                 */
                 _converse.api.emit('profileModalInitialized', this.model);
             },
 

src/converse-roomslist.js

@@ -177,6 +177,12 @@ converse.plugins.add('converse-roomslist', {
                 this.list_model.fetch();
                 this.render();
                 this.sortAndPositionAllItems();
+                /**
+                 * Triggered once the _converse.RoomsListView has been created and initialized.
+                 * @event _converse#roomsListInitialized
+                 * @example _converse.api.listen.on('roomsListInitialized', status => { ... });
+                 */
+                _converse.api.emit('roomsListInitialized');
             },
 
             render () {
@@ -270,7 +276,6 @@ converse.plugins.add('converse-roomslist', {
 
             model.browserStorage = new Backbone.BrowserStorage[storage](id);
             _converse.rooms_list_view = new _converse.RoomsListView({'model': model});
-            _converse.api.emit('roomsListInitialized');
         };
 
         _converse.api.listen.on('connected', async () =>  {

src/converse-rosterview.js

@@ -824,6 +824,14 @@ converse.plugins.add('converse-rosterview', {
                     this.trigger('rosterContactsFetchedAndProcessed');
                 });
                 this.createRosterFilter();
+
+                _converse.rosterview.render();
+                /**
+                 * Triggered once the _converse.RosterView instance has been created and initialized.
+                 * @event _converse#rosterViewInitialized
+                 * @example _converse.api.listen.on('rosterViewInitialized', () => { ... });
+                 */
+                _converse.api.emit('rosterViewInitialized');
             },
 
             render () {
@@ -1031,8 +1039,6 @@ converse.plugins.add('converse-rosterview', {
             _converse.rosterview = new _converse.RosterView({
                 'model': _converse.rostergroups
             });
-            _converse.rosterview.render();
-            _converse.api.emit('rosterViewInitialized');
         }
         _converse.api.listen.on('rosterInitialized', initRoster);
         _converse.api.listen.on('rosterReadyAfterReconnection', initRoster);

src/headless/converse-chatboxes.js

@@ -220,8 +220,9 @@ converse.plugins.add('converse-chatboxes', {
 
 
         /**
-         * The "_converse.ChatBox" namespace
+         * Represents an open/ongoing chat conversation.
          *
+         * @class
          * @namespace _converse.ChatBox
          * @memberOf _converse
          */
@@ -760,6 +761,16 @@ converse.plugins.add('converse-chatboxes', {
                 return new _converse.ChatBox(attrs, options);
             },
 
+            initialize () {
+                /**
+                 * Triggered once the _converse.ChatBoxes collection has been initialized.
+                 * @event _converse#chatBoxesInitialized
+                 * @example _converse.api.listen.on('chatBoxesInitialized', () => { ... });
+                 * @example _converse.api.waitUntil('chatBoxesInitialized').then(() => { ... });
+                 */
+                _converse.api.emit('chatBoxesInitialized');
+            },
+
             registerMessageHandler () {
                 _converse.connection.addHandler(stanza => {
                     this.onMessage(stanza);
@@ -796,6 +807,15 @@ converse.plugins.add('converse-chatboxes', {
                         chatbox.trigger('show');
                     }
                 });
+                /**
+                 * Triggered when a message stanza is been received and processed.
+                 * @event _converse#message
+                 * @type { object }
+                 * @property { _converse.ChatBox | _converse.ChatRoom } chatbox
+                 * @property { XMLElement } stanza
+                 * @example _converse.api.listen.on('message', obj => { ... });
+                 * @example _converse.api.waitUntil('chatBoxesFetched').then(() => { ... });
+                 */
                 _converse.api.emit('chatBoxesFetched');
             },
 
@@ -949,6 +969,14 @@ converse.plugins.add('converse-chatboxes', {
                         }
                     }
                 }
+                /**
+                 * Triggered when a message stanza is been received and processed
+                 * @event _converse#message
+                 * @type { object }
+                 * @property { _converse.ChatBox | _converse.ChatRoom } chatbox
+                 * @property { XMLElement } stanza
+                 * @example _converse.api.listen.on('message', obj => { ... });
+                 */
                 _converse.api.emit('message', {'stanza': original_stanza, 'chatbox': chatbox});
             },
 
@@ -998,6 +1026,14 @@ converse.plugins.add('converse-chatboxes', {
                         Strophe.LogLevel.ERROR);
                 }
             });
+            /**
+             * Triggered once any private chats have been automatically joined as
+             * specified by the `auto_join_private_chats` setting.
+             * See: https://conversejs.org/docs/html/configuration.html#auto-join-private-chats
+             * @event _converse#privateChatsAutoJoined
+             * @example _converse.api.listen.on('privateChatsAutoJoined', () => { ... });
+             * @example _converse.api.waitUntil('privateChatsAutoJoined').then(() => { ... });
+             */
             _converse.api.emit('privateChatsAutoJoined');
         }
 
@@ -1012,11 +1048,7 @@ converse.plugins.add('converse-chatboxes', {
             _converse.api.disco.own.features.add(Strophe.NS.OUTOFBAND);
         });
 
-        _converse.api.listen.on('pluginsInitialized', () => {
-            _converse.chatboxes = new _converse.ChatBoxes();
-            _converse.api.emit('chatBoxesInitialized');
-        });
-
+        _converse.api.listen.on('pluginsInitialized', () => (_converse.chatboxes = new _converse.ChatBoxes()));
         _converse.api.listen.on('presencesInitialized', () => _converse.chatboxes.onConnected());
         /************************ END Event Handlers ************************/
 

src/headless/converse-disco.js

@@ -94,11 +94,24 @@ converse.plugins.add('converse-disco', {
 
             onFeatureAdded (feature) {
                 feature.entity = this;
+                /**
+                 * Triggered when Converse has learned of a service provided by the XMPP server.
+                 * See XEP-0030.
+                 * @event _converse#serviceDiscovered
+                 * @type { Backbone.Model }
+                 * @example _converse.api.listen.on('featuresDiscovered', feature => { ... });
+                 */
                 _converse.api.emit('serviceDiscovered', feature);
             },
 
             onFieldAdded (field) {
                 field.entity = this;
+                /**
+                 * Triggered when Converse has learned of a disco extension field.
+                 * See XEP-0030.
+                 * @event _converse#discoExtensionFieldDiscovered
+                 * @example _converse.api.listen.on('discoExtensionFieldDiscovered', () => { ... });
+                 */
                 _converse.api.emit('discoExtensionFieldDiscovered', field);
             },
 
@@ -227,6 +240,12 @@ converse.plugins.add('converse-disco', {
             if (_converse.message_carbons) {
                 _converse.api.disco.own.features.add(Strophe.NS.CARBONS);
             }
+            /**
+             * Triggered in converse-disco once the core disco features of
+             * Converse have been added.
+             * @event _converse#addClientFeatures
+             * @example _converse.api.listen.on('addClientFeatures', () => { ... });
+             */
             _converse.api.emit('addClientFeatures');
             return this;
         }
@@ -250,6 +269,13 @@ converse.plugins.add('converse-disco', {
                     }
                 }
             });
+            /**
+             * Triggered as soon as Converse has processed the stream features as advertised by
+             * the server. If you want to check whether a stream feature is supported before
+             * proceeding, then you'll first want to wait for this event.
+             * @event _converse#streamFeaturesAdded
+             * @example _converse.api.listen.on('streamFeaturesAdded', () => { ... });
+             */
             _converse.api.emit('streamFeaturesAdded');
         }
 
@@ -268,6 +294,13 @@ converse.plugins.add('converse-disco', {
                 // create one.
                 _converse.disco_entities.create({'jid': _converse.domain});
             }
+            /**
+             * Triggered once the `converse-disco` plugin has been initialized and the
+             * `_converse.disco_entities` collection will be available and populated with at
+             * least the service discovery features of the user's own server.
+             * @event _converse#discoInitialized
+             * @example _converse.api.listen.on('discoInitialized', () => { ... });
+             */
             _converse.api.emit('discoInitialized');
         }
 

src/headless/converse-muc.js

@@ -168,6 +168,13 @@ converse.plugins.add('converse-muc', {
             return chatbox;
         }
 
+        /**
+         * Represents an open/ongoing groupchat conversation.
+         *
+         * @class
+         * @namespace _converse.ChatRoom
+         * @memberOf _converse
+         */
         _converse.ChatRoom = _converse.ChatBox.extend({
 
             defaults () {
@@ -474,7 +481,6 @@ converse.plugins.add('converse-muc', {
 
             directInvite (recipient, reason) {
                 /* Send a direct invitation as per XEP-0249
-                 *
                  * Parameters:
                  *    (String) recipient - JID of the person being invited
                  *    (String) reason - Optional reason for the invitation
@@ -505,6 +511,16 @@ converse.plugins.add('converse-muc', {
                     'id': _converse.connection.getUniqueId()
                 }).c('x', attrs);
                 _converse.api.send(invitation);
+                /**
+                 * After the user has sent out a direct invitation (as per XEP-0249),
+                 * to a roster contact, asking them to join a room.
+                 * @event _converse#chatBoxMaximized
+                 * @type { object }
+                 * @property { _converse.ChatRoom } room
+                 * @property { string } recipient - The JID of the person being invited
+                 * @property { string } reason - The original reason for the invitation
+                 * @example _converse.api.listen.on('chatBoxMaximized', view => { ... });
+                 */
                 _converse.api.emit('roomInviteSent', {
                     'room': this,
                     'recipient': recipient,
@@ -1106,6 +1122,14 @@ converse.plugins.add('converse-muc', {
                         // Accept default configuration
                         this.saveConfiguration().then(() => this.refreshRoomFeatures());
                     } else {
+                        /**
+                         * Triggered when a new room has been created which first needs to be configured
+                         * and when `auto_configure` is set to `false`.
+                         * Used by `_converse.ChatRoomView` in order to know when to render the
+                         * configuration form for a new room.
+                         * @event _converse.ChatRoom#configurationNeeded
+                         * @example _converse.api.listen.on('configurationNeeded', () => { ... });
+                         */
                         this.trigger('configurationNeeded');
                         return; // We haven't yet entered the groupchat, so bail here.
                     }
@@ -1380,6 +1404,13 @@ converse.plugins.add('converse-muc', {
                         Strophe.LogLevel.ERROR);
                 }
             });
+            /**
+             * Triggered once any rooms that have been configured to be automatically joined,
+             * specified via the _`auto_join_rooms` setting, have been entered.
+             * @event _converse#roomsAutoJoined
+             * @example _converse.api.listen.on('roomsAutoJoined', () => { ... });
+             * @example _converse.api.waitUntil('roomsAutoJoined').then(() => { ... });
+             */
             _converse.api.emit('roomsAutoJoined');
         }
 

src/headless/converse-roster.js

@@ -63,6 +63,14 @@ converse.plugins.add('converse-roster', {
             _converse.rostergroups = new _converse.RosterGroups();
             _converse.rostergroups.browserStorage = new Backbone.BrowserStorage[storage](
                 `converse.roster.groups${_converse.bare_jid}`);
+            /**
+             * Triggered once the `_converse.RosterContacts` and `_converse.RosterGroups` have
+             * been created, but not yet populated with data.
+             * This event is useful when you want to create views for these collections.
+             * @event _converse#chatBoxMaximized
+             * @example _converse.api.listen.on('rosterInitialized', () => { ... });
+             * @example _converse.api.waitUntil('rosterInitialized').then(() => { ... });
+             */
             _converse.api.emit('rosterInitialized');
         };
 
@@ -80,6 +88,12 @@ converse.plugins.add('converse-roster', {
                 _converse.send_initial_presence = true;
                 try {
                     await _converse.roster.fetchFromServer();
+                    /**
+                     * Triggered once roster contacts have been fetched. Used by the
+                     * `converse-rosterview.js` plugin to know when it can start to show the roster.
+                     * @event _converse#rosterContactsFetched
+                     * @example _converse.api.listen.on('rosterContactsFetched', () => { ... });
+                     */
                     _converse.api.emit('rosterContactsFetched');
                 } catch (reason) {
                     _converse.log(reason, Strophe.LogLevel.ERROR);
@@ -89,6 +103,13 @@ converse.plugins.add('converse-roster', {
             } else {
                 try {
                     await _converse.rostergroups.fetchRosterGroups();
+                    /**
+                     * Triggered once roster groups have been fetched. Used by the
+                     * `converse-rosterview.js` plugin to know when it can start alphabetically
+                     * position roster groups.
+                     * @event _converse#rosterGroupsFetched
+                     * @example _converse.api.listen.on('rosterGroupsFetched', () => { ... });
+                     */
                     _converse.api.emit('rosterGroupsFetched');
                     await _converse.roster.fetchRosterContacts();
                     _converse.api.emit('rosterContactsFetched');
@@ -223,6 +244,13 @@ converse.plugins.add('converse-roster', {
 
                 this.setChatBox();
 
+                /**
+                 * When a contact's presence status has changed.
+                 * The presence status is either `online`, `offline`, `dnd`, `away` or `xa`.
+                 * @event _converse#contactPresenceChanged
+                 * @type { _converse.RosterContact }
+                 * @example _converse.api.listen.on('contactPresenceChanged', contact => { ... });
+                 */
                 this.presence.on('change:show', () => _converse.api.emit('contactPresenceChanged', this));
                 this.presence.on('change:show', () => this.trigger('presenceChanged'));
             },
@@ -404,6 +432,13 @@ converse.plugins.add('converse-roster', {
                     _converse.send_initial_presence = true;
                     return _converse.roster.fetchFromServer();
                 } else {
+                    /**
+                     * The contacts roster has been retrieved from the local cache (`sessionStorage`).
+                     * @event _converse#cachedRoster
+                     * @type { _converse.RosterContacts }
+                     * @example _converse.api.listen.on('cachedRoster', (items) => { ... });
+                     * @example _converse.api.waitUntil('cachedRoster').then(items => { ... });
+                     */
                     _converse.api.emit('cachedRoster', collection);
                 }
             },
@@ -549,6 +584,12 @@ converse.plugins.add('converse-roster', {
                     return;
                 }
                 this.updateContact(items.pop());
+                /**
+                 * When the roster receives a push event from server (i.e. new entry in your contacts roster).
+                 * @event _converse#rosterPush
+                 * @type { XMLElement }
+                 * @example _converse.api.listen.on('rosterPush', iq => { ... });
+                 */
                 _converse.api.emit('rosterPush', iq);
                 return;
             },
@@ -590,6 +631,15 @@ converse.plugins.add('converse-roster', {
                     this.data.save('version', query.getAttribute('ver'));
                     _converse.session.save('roster_fetched', true);
                 }
+                /**
+                 * When the roster has been received from the XMPP server.
+                 * See also the `cachedRoster` event further up, which gets called instead of
+                 * `roster` if its already in `sessionStorage`.
+                 * @event _converse#roster
+                 * @type { XMLElement }
+                 * @example _converse.api.listen.on('roster', iq => { ... });
+                 * @example _converse.api.waitUntil('roster').then(iq => { ... });
+                 */
                 _converse.api.emit('roster', iq);
             },
 
@@ -644,6 +694,12 @@ converse.plugins.add('converse-roster', {
                     'requesting': true,
                     'nickname': nickname
                 };
+                /**
+                 * Triggered when someone has requested to subscribe to your presence (i.e. to be your contact).
+                 * @event _converse#contactRequest
+                 * @type { _converse.RosterContact }
+                 * @example _converse.api.listen.on('contactRequest', contact => { ... });
+                 */
                 _converse.api.emit('contactRequest', this.create(user_data));
             },
 
@@ -856,15 +912,27 @@ converse.plugins.add('converse-roster', {
             _converse.presences.browserStorage =
                 new Backbone.BrowserStorage.session(`converse.presences-${_converse.bare_jid}`);
             _converse.presences.fetch();
+            /**
+             * Triggered once the _converse.Presences collection has been
+             * initialized and its cached data fetched.
+             * Returns a boolean indicating whether this event has fired due to
+             * Converse having reconnected.
+             * @event _converse#presencesInitialized
+             * @type { bool }
+             * @example _converse.api.listen.on('presencesInitialized', reconnecting => { ... });
+             */
             _converse.api.emit('presencesInitialized', reconnecting);
         });
 
         _converse.api.listen.on('presencesInitialized', (reconnecting) => {
             if (reconnecting) {
-                // No need to recreate the roster, otherwise we lose our
-                // cached data. However we still emit an event, to give
-                // event handlers a chance to register views for the
-                // roster and its groups, before we start populating.
+                /**
+                 * Similar to `rosterInitialized`, but instead pertaining to reconnection.
+                 * This event indicates that the roster and its groups are now again
+                 * available after Converse.js has reconnected.
+                 * @event _converse#rosterReadyAfterReconnection
+                 * @example _converse.api.listen.on('rosterReadyAfterReconnection', () => { ... });
+                 */
                 _converse.api.emit('rosterReadyAfterReconnection');
             } else {
                 _converse.registerIntervalHandler();