More jsdoc docstrings as well as an intro page and JSON config
This commit is contained in:
JC Brand
parent
6f13676ee1
commit
45fc71c05d
4
Makefile
4
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
|
||||
|
||||
3
docs/source/conf.json
Normal file
3
docs/source/conf.json
Normal file
@ -0,0 +1,3 @@
|
||||
{
|
||||
"plugins": ["plugins/markdown"]
|
||||
}
|
||||
51
docs/source/jsdoc_intro.md
Normal file
51
docs/source/jsdoc_intro.md
Normal file
@ -0,0 +1,51 @@
|
||||
# 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();
|
||||
|
||||
@ -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,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user