More jsdoc docstrings as well as an intro page and JSON config

Makefile

@@ -231,6 +231,6 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-.PHONY: apidoc
+ePHONY: apidoc
 apidoc:
-	$(JSDOC) -d docs/html/api src/*.js
+	$(JSDOC) --readme docs/source/jsdoc_intro.md -c docs/source/conf.json -d docs/html/api src/*.js

docs/source/conf.json

+{
+    "plugins": ["plugins/markdown"]
+}

docs/source/jsdoc_intro.md

+# The Converse API documentation
+
+## The public and private API
+
+Converse has a public API and a private API.
+
+The reason we make this distinction between public and private is so that API
+methods which might can be used to "impersonate" the user, for example by
+sending messages on their behalf, are not available to random scripts running
+in the websites.
+
+The public API is accessible via the `window.converse` global and is therefore
+available to all JavaScript running in the page.
+
+The private API is only accessible to plugins, which have been whitelisted and
+registered before `converse.initialize` (which is a public API method) has been
+called. See the [plugin development](https://conversejs.org/docs/html/plugin_development.html)
+section for more info on writing plugins.
+
+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
+
+The Converse API is often 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
+groupings but single methods.
+
+The groupings logically group methods, such as standardised accessors and
+mutators:
+
+* .get
+* .set
+* .add
+* .remove
+
+So for example, to get a contact, you would do the following:
+
+    _converse.api.contacts.get('jid@example.com');
+
+To get multiple contacts, just pass in an array of jids:
+
+    _converse.api.contacts.get(['jid1@example.com', 'jid2@example.com']);
+
+To get all contacts, simply call ``get`` without any jids:
+
+    _converse.api.contacts.get();
+

src/converse-core.js

@@ -1350,12 +1350,83 @@
         }
     };
 
-    // The public API
+    /** 
+     * The Public API
+     * @namespace window
+     */
+
+    /**
+     * This namespace contains public API methods which are are
+     * accessible on the global window.converse object.
+     * They are public, because any JavaScript in the
+     * page can call them. Public methods therefore don’t expose any sensitive
+     * or closured data. To do that, you’ll need to create a plugin, which has
+     * access to the private API method.
+     *
+     * @namespace window.converse
+     * @memberOf window
+     */
     window.converse = {
+        /**
+         * Public API method which initializes Converse.
+         * This method must always be called when using Converse. 
+         *
+         * @memberOf window.converse
+         * @method initialize
+         * @param {object} config A map of [configuration-settings](https://conversejs.org/docs/html/configuration.html#configuration-settings).
+         *
+         * @example
+         *
+         * converse.initialize({
+         *     allow_otr: true,
+         *     auto_list_rooms: false,
+         *     auto_subscribe: false,
+         *     bosh_service_url: 'https://bind.example.com',
+         *     hide_muc_server: false,
+         *     i18n: locales['en'],
+         *     keepalive: true,
+         *     play_sounds: true,
+         *     prebind: false,
+         *     show_controlbox_by_default: true,
+         *     debug: false,
+         *     roster_groups: true
+         * });
+         */
         'initialize' (settings, callback) {
             return _converse.initialize(settings, callback);
         },
+        /**
+         * Exposes methods for adding and removing plugins. You'll need to write a plugin
+         * if you want to have access to the private API methods defined further down below.
+         * 
+         * For more information on plugins, read the section :ref:`writing-a-plugin`.
+         *
+         * @property {object} window.converse
+         * @memberOf window.converse
+         */
         'plugins': {
+            /** Registers a new plugin.
+             * 
+             * @memberOf window.converse.plugins
+             * @method add
+             * @param {string} name The name of the plugin
+             * @param {object} plugin The plugin object
+             *
+             * @example
+             * 
+             *  const plugin = {
+             *      initialize: function () {
+             *          // Gets called as soon as the plugin has been loaded.
+             * 
+             *          // Inside this method, you have access to the private
+             *          // API via `_covnerse.api`.
+             *
+             *          // The private _converse object contains the core logic
+             *          // and data-structures of Converse.
+             *      }
+             *  }
+             *  converse.plugins.add('myplugin', plugin);
+             */
             'add' (name, plugin) {
                 plugin.__name__ = name;
                 if (!_.isUndefined(_converse.pluggable.plugins[name])) {
@@ -1367,6 +1438,24 @@
                 }
             }
         },
+        /**
+         * 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.
+         */
         'env': {
             '$build': $build,
             '$iq': $iq,