All API methods of converse-core are now documented with jsdoc

docs/source/developer_api.rst

@@ -572,7 +572,7 @@ This grouping collects API functions related to the current logged in user.
 jid
 ~~~
 
-Return's the current user's full JID (Jabber ID).
+Returns the current user's full JID (Jabber ID).
 
 .. code-block:: javascript
 
@@ -907,7 +907,7 @@ To return an array of views, provide an array of JIDs:
 The **listen** grouping
 -----------------------
 
-Converse emits events to which you can subscribe from your own JavaScript.
+Converse emits events to which you can subscribe to.
 
 Concerning events, the following methods are available under the "listen"
 grouping:
@@ -1201,7 +1201,7 @@ For example:
 get(key)
 ~~~~~~~~
 
-Returns the value of a configuration settings. For example:
+Returns the value of the particular configuration setting. For example:
 
 .. code-block:: javascript
 

docs/source/jsdoc_intro.md

@@ -21,15 +21,15 @@ Inside a plugin, you can get access to the `_converse.api` object. Note the
 underscore in front of `_converse`, which indicates that this is a private,
 closured object.
 
-## API Groupings
+## API Namespaces
 
-The Converse API is often broken up into different logical "groupings" (for
+The Converse API is often broken up into different logical "namespaces" (for
 example `converse.plugins` or `converse.contacts`).
 
 There are some exceptions to this, like `converse.initialize`, which aren't
-groupings but single methods.
+namespaces but single methods.
 
-The groupings logically group methods, such as standardised accessors and
+The namespaces logically group methods, such as standardised accessors and
 mutators:
 
 * .get

src/converse-core.js

@@ -58,6 +58,13 @@
         'imports': { '_': _ }
     };
 
+    /** 
+     * A private, closured object containing the private api (via
+     * `_converse.api`) as well as private methods and internal
+     * data-structures.
+     *
+     * @namespace _converse
+     */
     const _converse = {
         'templates': {},
         'promises': {}
@@ -1224,33 +1231,130 @@
         return init_promise;
     };
 
-    // API methods only available to plugins
+    /** 
+     * ### The private API
+     *
+     * The private API methods are only accessible via the closured `_converse`
+     * object, which is only available to plugins.
+     * 
+     * These methods are kept private (i.e. not global) because they may return
+     * sensitive data which should be kept off-limits to other 3rd-party scripts
+     * that might be running in the page.
+     *
+     * @namespace _converse.api
+     * @memberOf _converse
+     */
     _converse.api = {
+        /**
+         * This grouping collects API functions related to the XMPP connection.
+         *
+         * @namespace _converse.api.connection
+         * @memberOf _converse.api
+         */
         'connection': {
+            /**
+             * @method _converse.api.connection.connected
+             * @memberOf _converse.api.connection
+             * @returns {boolean} Whether there is an established connection or not.
+             */
             'connected' () {
                 return _converse.connection && _converse.connection.connected || false;
             },
+            /**
+             * Terminates the connection.
+             *
+             * @method _converse.api.connection.disconnect
+             * @memberOf _converse.api.connection
+             */
             'disconnect' () {
                 _converse.connection.disconnect();
             },
         },
+
+        /**
+         * Lets you emit (i.e. trigger) events, which can be listened to via
+         * `_converse.api.listen.on` or `_converse.api.listen.once`
+         * (see [_converse.api.listen](http://localhost:8000/docs/html/api/-_converse.api.listen.html)).
+         *
+         * @method _converse.api.connection.emit
+         */
         'emit' () {
             _converse.emit.apply(_converse, arguments);
         },
+
+        /**
+         * This grouping collects API functions related to the current logged in user.
+         *
+         * @namespace _converse.api.user
+         * @memberOf _converse.api
+         */
         'user': {
+            /**
+             * @method _converse.api.user.jid
+             * @returns {string} The current user's full JID (Jabber ID)
+             * @example _converse.api.user.jid())
+             */
             'jid' () {
                 return _converse.connection.jid;
             },
+            /**
+             * Logs the user in.
+             *
+             * If called without any parameters, Converse will try
+             * to log the user in by calling the `prebind_url` or `credentials_url` depending
+             * on whether prebinding is used or not.
+             *
+             * @method _converse.api.user.login
+             * @param {object} [credentials] An object with the credentials.
+             * @example
+             * converse.plugins.add('myplugin', {
+             *     initialize: function () {
+             *
+             *         this._converse.api.user.login({
+             *             'jid': 'dummy@example.com',
+             *             'password': 'secret'
+             *         });
+             *
+             *     }
+             * });
+             */
             'login' (credentials) {
                 _converse.logIn(credentials);
             },
+            /**
+             * Logs the user out of the current XMPP session.
+             *
+             * @method _converse.api.user.logout
+             * @example _converse.api.user.logout();
+             */
             'logout' () {
                 _converse.logOut();
             },
+            /**
+             * Set and get the user's chat status, also called their *availability*.
+             *
+             * @namespace _converse.api.user.status
+             * @memberOf _converse.api.user
+             */
             'status': {
+                /** Return the current user's availability status.
+                 * 
+                 * @method _converse.api.user.status.get
+                 * @example _converse.api.user.status.get();
+                 */
                 'get' () {
                     return _converse.xmppstatus.get('status');
                 },
+                /** 
+                 * The user's status can be set to one of the following values:
+                 *
+                 * @method _converse.api.user.status.set
+                 * @param {string} value The user's chat status (e.g. 'away', 'dnd', 'offline', 'online', 'unavailable' or 'xa')
+                 * @param {string} [message] A custom status message
+                 *
+                 * @example this._converse.api.user.status.set('dnd');
+                 * @example this._converse.api.user.status.set('dnd', 'In a meeting');
+                 */
                 'set' (value, message) {
                     const data = {'status': value};
                     if (!_.includes(_.keys(_converse.STATUS_WEIGHTS), value)) {
@@ -1262,27 +1366,91 @@
                     _converse.xmppstatus.sendPresence(value);
                     _converse.xmppstatus.save(data);
                 },
+
+                /**
+                 * Set and retrieve the user's custom status message.
+                 *
+                 * @namespace _converse.api.user.status.message
+                 * @memberOf _converse.api.user.status
+                 */
                 'message': {
+                    /**
+                     * @method _converse.api.user.status.message.get
+                     * @returns {string} The status message
+                     * @example const message = _converse.api.user.status.message.get()
+                     */
                     'get' () {
                         return _converse.xmppstatus.get('status_message');
                     },
-                    'set' (stat) {
-                        _converse.xmppstatus.save({'status_message': stat});
+                    /**
+                     * @method _converse.api.user.status.message.set
+                     * @param {string} status The status message
+                     * @example _converse.api.user.status.message.set('In a meeting');
+                     */
+                    'set' (status) {
+                        _converse.xmppstatus.save({'status_message': status});
                     }
                 }
             },
         },
+
+        /**
+         * This grouping allows access to the configuration settings of Converse.
+         *
+         * @namespace _converse.api.settings
+         * @memberOf _converse.api
+         */
         'settings': {
+            /**
+             * Allows new configuration settings to be specified, or new default values for
+             * existing configuration settings to be specified.
+             *
+             * @method _converse.api.settings.update
+             * @param {object} settings The configuration settings
+             * @example 
+             * _converse.api.settings.update({
+             *    'enable_foo': true
+             * });
+             *
+             * // The user can then override the default value of the configuration setting when
+             * // calling `converse.initialize`.
+             * converse.initialize({
+             *     'enable_foo': false
+             * });
+             */
             'update' (settings) {
                 u.merge(_converse.default_settings, settings);
                 u.merge(_converse, settings);
                 u.applyUserSettings(_converse, settings, _converse.user_settings);
             },
+            /**
+             * @method _converse.api.settings.get
+             * @returns {*} Value of the particular configuration setting.
+             * @example _converse.api.settings.get("play_sounds");
+             */
             'get' (key) {
                 if (_.includes(_.keys(_converse.default_settings), key)) {
                     return _converse[key];
                 }
             },
+            /**
+             * Set one or many configuration settings.
+             *
+             * Note, this is not an alternative to calling `converse.initialize`, which still needs
+             * to be called. Generally, you'd use this method after Converse is already
+             * running and you want to change the configuration on-the-fly.
+             *
+             * @method _converse.api.settings.set
+             * @param {Object} [settings] An object containing configuration settings.
+             * @param {string} [key] Alternatively to passing in an object, you can pass in a key and a value.
+             * @param {string} [value]
+             * @example _converse.api.settings.set("play_sounds", true);
+             * @example
+             * _converse.api.settings.set({
+             *     "play_sounds", true,
+             *     "hide_offline_users" true
+             * });
+             */
             'set' (key, val) {
                 const o = {};
                 if (_.isObject(key)) {
@@ -1293,13 +1461,71 @@
                 }
             }
         },
+
+        /**
+         * Converse and its plugins emit various events which you can listen to via the
+         * [_converse.api.listen](http://localhost:8000/docs/html/api/-_converse.api.listen.html)
+         * namespace.
+         * 
+         * Some of these events are also available as [ES2015 Promises](http://es6-features.org/#PromiseUsage)
+         * although not all of them could logically act as promises, since some events
+         * might be fired multpile times whereas promises are to be resolved (or
+         * rejected) only once.
+         * 
+         * Events which are also promises include:
+         * 
+         * * [cachedRoster](/docs/html/events.html#cachedroster)
+         * * [chatBoxesFetched](/docs/html/events.html#chatBoxesFetched)
+         * * [pluginsInitialized](/docs/html/events.html#pluginsInitialized)
+         * * [roster](/docs/html/events.html#roster)
+         * * [rosterContactsFetched](/docs/html/events.html#rosterContactsFetched)
+         * * [rosterGroupsFetched](/docs/html/events.html#rosterGroupsFetched)
+         * * [rosterInitialized](/docs/html/events.html#rosterInitialized)
+         * * [statusInitialized](/docs/html/events.html#statusInitialized)
+         * * [roomsPanelRendered](/docs/html/events.html#roomsPanelRendered)
+         * 
+         * The various plugins might also provide promises, and they do this by using the
+         * `promises.add` api method.
+         *
+         * @namespace _converse.api.promises
+         * @memberOf _converse.api
+         */
         'promises': {
+            /**
+             * By calling `promises.add`, a new [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
+             * is made available for other code or plugins to depend on via the
+             * `_converse.api.waitUntil` method.
+             * 
+             * Generally, it's the responsibility of the plugin which adds the promise to
+             * also resolve it.
+             * 
+             * This is done by calling `_converse.api.emit`, which not only resolves the
+             * promise, but also emits an event with the same name (which can be listened to
+             * via `_converse.api.listen`).
+             * 
+             * @method _converse.api.promises.add
+             * @param {string|array} [name|names] The name or an array of names for the promise(s) to be added
+             * @example _converse.api.promises.add('foo-completed');
+             */
             'add' (promises) {
                 promises = _.isArray(promises) ? promises : [promises]
                 _.each(promises, addPromise);
             }
         },
+
+        /**
+         * This namespace lets you access the BOSH tokens
+         *
+         * @namespace _converse.api.tokens
+         * @memberOf _converse.api
+         */
         'tokens': {
+            /**
+             * @method _converse.api.tokens.get
+             * @param {string} [id] The type of token to return ('rid' or 'sid').
+             * @returns 'string' A token, either the RID or SID token depending on what's asked for.
+             * @example _converse.api.tokens.get('rid');
+             */
             'get' (id) {
                 if (!_converse.expose_rid_and_sid || _.isUndefined(_converse.connection)) {
                     return null;
@@ -1311,10 +1537,64 @@
                 }
             }
         },
+
+        /**
+         * Converse emits events to which you can subscribe to.
+         * 
+         * The `listen` namespace exposes methods for creating event listeners
+         * (aka handlers) for these events.
+         *
+         * @namespace _converse.api.listen
+         * @memberOf _converse
+         */
         'listen': {
+            /**
+             * Lets you listen to an event exactly once.
+
+             * @method _converse.api.listen.once
+             * @param {string} name The event's name
+             * @param {function} callback The callback method to be called when the event is emitted.
+             * @param {object} [context] The value of the `this` parameter for the callback.
+             * @example _converse.api.listen.once('message', function (messageXML) { ... });
+             */
             'once': _converse.once.bind(_converse),
+
+            /**
+             * Lets you subscribe to an event.
+             *
+             * Every time the event fires, the callback method specified by `callback` will be called.
+
+             * @method _converse.api.listen.on
+             * @param {string} name The event's name
+             * @param {function} callback The callback method to be called when the event is emitted.
+             * @param {object} [context] The value of the `this` parameter for the callback.
+             * @example _converse.api.listen.on('message', function (messageXML) { ... });
+             */
             'on': _converse.on.bind(_converse),
+
+            /**
+             * To stop listening to an event, you can use the ``not`` method.
+             *
+             * Every time the event fires, the callback method specified by `callback` will be called.
+
+             * @method _converse.api.listen.not
+             * @param {string} name The event's name
+             * @param {function} callback The callback method that is to no longer be called when the event fires
+             * @example _converse.api.listen.not('message', function (messageXML);
+             */
             'not': _converse.off.bind(_converse),
+
+            /**
+             * Subscribe to an incoming stanza
+             *
+             * Every a matched stanza is received, the callback method specified by `callback` will be called.
+
+             * @method _converse.api.listen.stanza
+             * @param {string} name The stanza's name
+             * @param {object} options Matching options
+             * (e.g. 'ns' for namespace, 'type' for stanza type, also 'id' and 'from');
+             * @param {function} handler The callback method to be called when the stanza appears
+             */
             'stanza' (name, options, handler) {
                 if (_.isFunction(options)) {
                     handler = options;
@@ -1333,6 +1613,13 @@
                 );
             },
         },
+
+        /**
+         * Wait until a promise is resolved
+         *
+         * @method _converse.api.waitUntil
+         * @param {string} name The name of the promise
+         */
         'waitUntil' (name) {
             const promise = _converse.promises[name];
             if (_.isUndefined(promise)) {
@@ -1340,9 +1627,21 @@
             }
             return promise;
         },
+        /**
+         * Send a stanza
+         *
+         * @method _converse.api.send
+         */
         'send' (stanza) {
             _converse.connection.send(stanza);
         },
+        /**
+         * Send an IQ stanza and receive a promise
+         *
+         * @method _converse.api.sendIQ
+         * @returns {Promise} A promise which resolves when we receive a `result` stanza
+         * or is rejected when we receive an `error` stanza.
+         */
         'sendIQ' (stanza) {
             return new Promise((resolve, reject) => {
                 _converse.connection.sendIQ(stanza, resolve, reject, _converse.IQ_TIMEOUT);
@@ -1437,24 +1736,25 @@
                     _converse.pluggable.plugins[name] = plugin;
                 }
             }
+
         },
         /**
          * Utility methods and globals from bundled 3rd party libraries.
          * @memberOf window.converse
          *
-         * @property {function} converse.env.$build        - Creates a Strophe.Builder, for creating stanza objects.
-         * @property {function} converse.env.$iq           - Creates a Strophe.Builder with an <iq/> element as the root.
-         * @property {function} converse.env.$msg          - Creates a Strophe.Builder with an <message/> element as the root.
-         * @property {function} converse.env.$pres         - Creates a Strophe.Builder with an <presence/> element as the root.
-         * @property {object} converse.env.Backbone      - The [Backbone](http://backbonejs.org) object used by Converse to create models and views.
-         * @property {function} converse.env.Promise       - The Promise implementation used by Converse.
-         * @property {function} converse.env.Strophe       - The [Strophe](http://strophe.im/strophejs) XMPP library used by Converse.
-         * @property {object} converse.env._             - The instance of [lodash](http://lodash.com) used by Converse.
-         * @property {function} converse.env.f             - And instance of Lodash with its methods wrapped to produce immutable auto-curried iteratee-first data-last methods.
-         * @property {function} converse.env.b64_sha1      - Utility method from Strophe for creating base64 encoded sha1 hashes.
-         * @property {object} converse.env.moment        - [Moment](https://momentjs.com) date manipulation library.
-         * @property {function} converse.env.sizzle        - [Sizzle](https://sizzlejs.com) CSS selector engine.
-         * @property {object} converse.env.utils         - Module containing common utility methods used by Converse.
+         * @property {function} converse.env.$build    - Creates a Strophe.Builder, for creating stanza objects.
+         * @property {function} converse.env.$iq       - Creates a Strophe.Builder with an <iq/> element as the root.
+         * @property {function} converse.env.$msg      - Creates a Strophe.Builder with an <message/> element as the root.
+         * @property {function} converse.env.$pres     - Creates a Strophe.Builder with an <presence/> element as the root.
+         * @property {object} converse.env.Backbone    - The [Backbone](http://backbonejs.org) object used by Converse to create models and views.
+         * @property {function} converse.env.Promise   - The Promise implementation used by Converse.
+         * @property {function} converse.env.Strophe   - The [Strophe](http://strophe.im/strophejs) XMPP library used by Converse.
+         * @property {object} converse.env._           - The instance of [lodash](http://lodash.com) used by Converse.
+         * @property {function} converse.env.f         - And instance of Lodash with its methods wrapped to produce immutable auto-curried iteratee-first data-last methods.
+         * @property {function} converse.env.b64_sha1  - Utility method from Strophe for creating base64 encoded sha1 hashes.
+         * @property {object} converse.env.moment      - [Moment](https://momentjs.com) date manipulation library.
+         * @property {function} converse.env.sizzle    - [Sizzle](https://sizzlejs.com) CSS selector engine.
+         * @property {object} converse.env.utils       - Module containing common utility methods used by Converse.
          */
         'env': {
             '$build': $build,