Add jsdoc docstrings to `chats` API.

Link to the jsdoc output from the Sphinx docs

Makefile

@@ -227,6 +227,7 @@ check: eslint
 html:
 	rm -rf $(BUILDDIR)/html
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	make apidoc
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 

docs/source/conf.py

 # -*- coding: utf-8 -*-
 #
-# Converse.js documentation build configuration file, created by
+# Converse documentation build configuration file, created by
 # sphinx-quickstart on Fri Apr 26 20:48:03 2013.
 #
 # This file is execfile()d with the current directory set to its containing dir.
@@ -40,8 +40,8 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'Converse.js'
-copyright = u'2017, JC Brand'
+project = u'Converse'
+copyright = u'2018, JC Brand'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -108,7 +108,7 @@ html_logo = "_static/conversejs_small.png"
 # theme further.
 html_theme_options = {
     # Navigation bar title. (Default: ``project`` value)
-    'navbar_title': "Converse.js",
+    'navbar_title': "Converse",
     # Tab name for entire site. (Default: "Site")
     'navbar_site_name': "Table of Contents",
     # A list of tuples containing pages or urls to link to.
@@ -229,7 +229,7 @@ latex_elements = {
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'Conversejs.tex', u'Converse.js Documentation',
+  ('index', 'Conversejs.tex', u'Converse Documentation',
    u'JC Brand', 'manual'),
 ]
 
@@ -259,7 +259,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'conversejs', u'Converse.js Documentation',
+    ('index', 'conversejs', u'Converse Documentation',
      [u'JC Brand'], 1)
 ]
 
@@ -273,8 +273,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'Conversejs', u'Converse.js Documentation',
-   u'JC Brand', 'Conversejs', 'Open Source XMPP webchat',
+  ('index', 'Conversejs', u'Converse Documentation',
+   u'JC Brand', 'Converse', 'Open Source XMPP webchat',
    'Miscellaneous'),
 ]
 

docs/source/developer_api.rst

@@ -2,12 +2,12 @@
 
     <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
 
-=============================
-The converse.js developer API
-=============================
+=========================
+The old API documentation
+=========================
 
-.. note:: The API documented here is available in Converse.js 0.8.4 and higher.
-        Earlier versions of Converse.js might have different API methods or none at all.
+.. note:: The API documented here is available in Converse 0.8.4 and higher.
+        Earlier versions of Converse might have different API methods or none at all.
 
 .. note:: From version 3.0.0 and onwards many API methods have been made
         private and available to plugins only. This means that if you want to
@@ -15,7 +15,7 @@ The converse.js developer API
         access it. This change is done to avoid leakage of sensitive data to
         malicious or non-whitelisted scripts.
 
-The Converse.js API is broken up into different logical "groupings" (for
+The Converse API is broken up into different logical "groupings" (for
 example ``converse.plugins`` or ``converse.contacts``).
 
 There are some exceptions to this, like ``converse.initialize``, which aren't
@@ -58,8 +58,8 @@ initialize
 
 .. note:: This method is the one exception of a method which is not logically grouped as explained above.
 
-Publich API method which initializes converse.js.
-This method must always be called when using converse.js.
+Publich API method which initializes Converse.
+This method must always be called when using Converse.
 
 The `initialize` method takes a map of :ref:`configuration-settings`.
 
@@ -105,7 +105,7 @@ Registers a new plugin.
 
             // Inside this method, you have access to the closured
             // _converse object, which contains the core logic and data
-            // structures of converse.js
+            // structures of Converse
         }
     }
     converse.plugins.add('myplugin', plugin);
@@ -182,7 +182,7 @@ two important ways:
 * A handler registered for a promise, will still fire *after* the promise has
   been resolved, which is not the case with an event handler.
 
-Converse.js has the following promises:
+Converse has the following promises:
 
 * :ref:`cachedRoster`
 * :ref:`chatBoxesFetched`
@@ -210,7 +210,7 @@ already by that time.
 The **archive** grouping
 ------------------------
 
-Converse.js supports the *Message Archive Management*
+Converse supports the *Message Archive Management*
 (`XEP-0313 <https://xmpp.org/extensions/xep-0313.html>`_) protocol,
 through which it is able to query an XMPP server for archived messages.
 
@@ -263,12 +263,12 @@ the returned messages.
 
 **Waiting until server support has been determined**
 
-The query method will only work if converse.js has been able to determine that
+The query method will only work if Converse has been able to determine that
 the server supports MAM queries, otherwise the following error will be raised:
 
 - *This server does not support XEP-0313, Message Archive Management*
 
-The very first time converse.js loads in a browser tab, if you call the query
+The very first time Converse loads in a browser tab, if you call the query
 API too quickly, the above error might appear because service discovery has not
 yet been completed.
 
@@ -453,7 +453,7 @@ Paramters:
 get
 ***
 
-Returns all of the identities registered for this client (i.e. instance of Converse.js).
+Returns all of the identities registered for this client (i.e. instance of Converse).
 
 .. code-block:: javascript
 
@@ -473,17 +473,17 @@ Paramters:
 * (String) name
 * (String) lang
 
-Lets you add new identities for this client (i.e. instance of Converse.js).
+Lets you add new identities for this client (i.e. instance of Converse).
 
 .. code-block:: javascript
 
-    _converse.api.disco.own.identities.add('client', 'web', 'Converse.js');
+    _converse.api.disco.own.identities.add('client', 'web', 'Converse');
 
 
 get
 ***
 
-Returns all of the identities registered for this client (i.e. instance of Converse.js).
+Returns all of the identities registered for this client (i.e. instance of Converse).
 
 .. code-block:: javascript
 
@@ -602,7 +602,7 @@ Logs the user in. This method can accept a map with the credentials, like this:
         }
     });
 
-or it can be called without any parameters, in which case converse.js will try
+or it can be called without any parameters, in which case Converse will try
 to log the user in by calling the `prebind_url` or `credentials_url` depending
 on whether prebinding is used or not.
 
@@ -877,40 +877,6 @@ To return an array of chats, provide an array of JIDs:
     });
 
 
-*The returned chat object contains the following methods:*
-
-+-------------------+------------------------------------------+
-| Method            | Description                              |
-+===================+==========================================+
-| close             | Close the chat.                          |
-+-------------------+------------------------------------------+
-| focus             | Focuses the chat textarea                |
-+-------------------+------------------------------------------+
-| model.endOTR      | End an OTR (Off-the-record) session.     |
-+-------------------+------------------------------------------+
-| model.get         | Get an attribute (i.e. accessor).        |
-+-------------------+------------------------------------------+
-| model.initiateOTR | Start an OTR (off-the-record) session.   |
-+-------------------+------------------------------------------+
-| model.maximize    | Minimize the chat.                       |
-+-------------------+------------------------------------------+
-| model.minimize    | Maximize the chat.                       |
-+-------------------+------------------------------------------+
-| model.set         | Set an attribute (i.e. mutator).         |
-+-------------------+------------------------------------------+
-| show              | Opens/shows the chat.                    |
-+-------------------+------------------------------------------+
-
-*The get and set methods can be used to retrieve and change the following attributes:*
-
-+-------------+-----------------------------------------------------+
-| Attribute   | Description                                         |
-+=============+=====================================================+
-| height      | The height of the chat.                             |
-+-------------+-----------------------------------------------------+
-| url         | The URL of the chat heading.                        |
-+-------------+-----------------------------------------------------+
-
 The **chatviews** grouping
 --------------------------
 
@@ -941,7 +907,7 @@ To return an array of views, provide an array of JIDs:
 The **listen** grouping
 -----------------------
 
-Converse.js emits events to which you can subscribe from your own JavaScript.
+Converse emits events to which you can subscribe from your own JavaScript.
 
 Concerning events, the following methods are available under the "listen"
 grouping:
@@ -1139,7 +1105,7 @@ JIDs.
 The **promises** grouping
 -------------------------
 
-Converse.js and its plugins emit various events which you can listen to via the
+Converse and its plugins emit various events which you can listen to via the
 :ref:`listen-grouping`.
 
 Some of these events are also available as `ES2015 Promises <http://es6-features.org/#PromiseUsage>`_,
@@ -1198,7 +1164,7 @@ For example:
 The **settings** grouping
 -------------------------
 
-This grouping allows access to the configuration settings of converse.js.
+This grouping allows access to the configuration settings of Converse.
 
 .. _`settings-update`:
 
@@ -1279,7 +1245,7 @@ or :
     });
 
 Note, this is not an alternative to calling ``converse.initialize``, which still needs
-to be called. Generally, you'd use this method after converse.js is already
+to be called. Generally, you'd use this method after Converse is already
 running and you want to change the configuration on-the-fly.
 
 The **tokens** grouping

docs/source/development.rst

@@ -8,13 +8,13 @@
 Development
 ===========
 
-Welcome to the developer documentation of converse.js. Read the documentation
+Welcome to the developer documentation of Converse. Read the documentation
 linked to below, if you want to add new features or create your own customized
-version of converse.js.
+version of Converse.
 
-Converse.js itself composed of plugins, and exposes an API with which you can
+Converse itself composed of plugins, and exposes an API with which you can
 create and register your own plugins. This is the recommended way to customize
-or add new functionality to converse.js.
+or add new functionality to Converse.
 
 .. toctree::
    :maxdepth: 2
@@ -22,6 +22,7 @@ or add new functionality to converse.js.
    developer_guidelines
    style_guide
    plugin_development
+   api/index
    developer_api
    events 
    other_frameworks

src/converse-chatboxes.js

@@ -873,6 +873,11 @@
 
             /************************ BEGIN API ************************/
             _.extend(_converse.api, {
+                /**
+                 * The "chats" grouping (used for one-on-one chats)
+                 *
+                 * @namespace
+                 */
                 'chats': {
                     'create' (jids, attrs) {
                         if (_.isUndefined(jids)) {
@@ -882,7 +887,6 @@
                             );
                             return null;
                         }
-
                         if (_.isString(jids)) {
                             if (attrs && !_.get(attrs, 'fullname')) {
                                 attrs.fullname = _.get(_converse.api.contacts.get(jids), 'attributes.fullname');
@@ -899,6 +903,40 @@
                             return _converse.chatboxes.getChatBox(jid, attrs, true).trigger('show');
                         });
                     },
+
+                    /**
+                     * Opens a new one-on-one chat.
+                     *
+                     * @function
+                     *
+                     * @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
+                     * @returns {Promise} Promise which resolves with the Backbone.Model representing the chat.
+                     *
+                     * @example
+                     * // To open a single chat, provide the JID of the contact you're chatting with in that chat:
+                     * converse.plugins.add('myplugin', {
+                     *     initialize: function() {
+                     *         var _converse = this._converse;
+                     *         // Note, buddy@example.org must be in your contacts roster!
+                     *         _converse.api.chats.open('buddy@example.com').then((chat) => {
+                     *             // Now you can do something with the chat model
+                     *         });
+                     *     }
+                     * });
+                     *
+                     * @example
+                     * // To open an array of chats, provide an array of JIDs:
+                     * converse.plugins.add('myplugin', {
+                     *     initialize: function () {
+                     *         var _converse = this._converse;
+                     *         // Note, these users must first be in your contacts roster!
+                     *         _converse.api.chats.open(['buddy1@example.com', 'buddy2@example.com']).then((chats) => {
+                     *             // Now you can do something with the chat models
+                     *         });
+                     *     }
+                     * });
+                     *
+                     */
                     'open' (jids, attrs) {
                         return new Promise((resolve, reject) => {
                             Promise.all([
@@ -917,6 +955,28 @@
                             }).catch(_.partial(_converse.log, _, Strophe.LogLevel.FATAL));
                         });
                     },
+
+                    /**
+                     * Returns a chat model. The chat should already be open.
+                     *
+                     * @function
+                     *
+                     * @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
+                     * @returns {Backbone.Model}
+                     *
+                     * @example
+                     * // To return a single chat, provide the JID of the contact you're chatting with in that chat:
+                     * const model = _converse.api.chats.get('buddy@example.com');
+                     *
+                     * @example
+                     * // To return an array of chats, provide an array of JIDs:
+                     * const models = _converse.api.chats.get(['buddy1@example.com', 'buddy2@example.com']);
+                     *
+                     * @example
+                     * // To return all open chats, call the method without any parameters::
+                     * const models = _converse.api.chats.get();
+                     *
+                     */
                     'get' (jids) {
                         if (_.isUndefined(jids)) {
                             const result = [];