Add jsdoc docstrings to chats
API.
Link to the jsdoc output from the Sphinx docs
This commit is contained in:
parent
506aa33131
commit
dc4c832fce
1
Makefile
1
Makefile
@ -227,6 +227,7 @@ check: eslint
|
|||||||
html:
|
html:
|
||||||
rm -rf $(BUILDDIR)/html
|
rm -rf $(BUILDDIR)/html
|
||||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||||
|
make apidoc
|
||||||
@echo
|
@echo
|
||||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||||
|
|
||||||
|
@ -1,6 +1,6 @@
|
|||||||
# -*- coding: utf-8 -*-
|
# -*- 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.
|
# sphinx-quickstart on Fri Apr 26 20:48:03 2013.
|
||||||
#
|
#
|
||||||
# This file is execfile()d with the current directory set to its containing dir.
|
# This file is execfile()d with the current directory set to its containing dir.
|
||||||
@ -40,8 +40,8 @@ source_suffix = '.rst'
|
|||||||
master_doc = 'index'
|
master_doc = 'index'
|
||||||
|
|
||||||
# General information about the project.
|
# General information about the project.
|
||||||
project = u'Converse.js'
|
project = u'Converse'
|
||||||
copyright = u'2017, JC Brand'
|
copyright = u'2018, JC Brand'
|
||||||
|
|
||||||
# The version info for the project you're documenting, acts as replacement for
|
# The version info for the project you're documenting, acts as replacement for
|
||||||
# |version| and |release|, also used in various other places throughout the
|
# |version| and |release|, also used in various other places throughout the
|
||||||
@ -108,7 +108,7 @@ html_logo = "_static/conversejs_small.png"
|
|||||||
# theme further.
|
# theme further.
|
||||||
html_theme_options = {
|
html_theme_options = {
|
||||||
# Navigation bar title. (Default: ``project`` value)
|
# Navigation bar title. (Default: ``project`` value)
|
||||||
'navbar_title': "Converse.js",
|
'navbar_title': "Converse",
|
||||||
# Tab name for entire site. (Default: "Site")
|
# Tab name for entire site. (Default: "Site")
|
||||||
'navbar_site_name': "Table of Contents",
|
'navbar_site_name': "Table of Contents",
|
||||||
# A list of tuples containing pages or urls to link to.
|
# 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
|
# Grouping the document tree into LaTeX files. List of tuples
|
||||||
# (source start file, target name, title, author, documentclass [howto/manual]).
|
# (source start file, target name, title, author, documentclass [howto/manual]).
|
||||||
latex_documents = [
|
latex_documents = [
|
||||||
('index', 'Conversejs.tex', u'Converse.js Documentation',
|
('index', 'Conversejs.tex', u'Converse Documentation',
|
||||||
u'JC Brand', 'manual'),
|
u'JC Brand', 'manual'),
|
||||||
]
|
]
|
||||||
|
|
||||||
@ -259,7 +259,7 @@ latex_documents = [
|
|||||||
# One entry per manual page. List of tuples
|
# One entry per manual page. List of tuples
|
||||||
# (source start file, name, description, authors, manual section).
|
# (source start file, name, description, authors, manual section).
|
||||||
man_pages = [
|
man_pages = [
|
||||||
('index', 'conversejs', u'Converse.js Documentation',
|
('index', 'conversejs', u'Converse Documentation',
|
||||||
[u'JC Brand'], 1)
|
[u'JC Brand'], 1)
|
||||||
]
|
]
|
||||||
|
|
||||||
@ -273,8 +273,8 @@ man_pages = [
|
|||||||
# (source start file, target name, title, author,
|
# (source start file, target name, title, author,
|
||||||
# dir menu entry, description, category)
|
# dir menu entry, description, category)
|
||||||
texinfo_documents = [
|
texinfo_documents = [
|
||||||
('index', 'Conversejs', u'Converse.js Documentation',
|
('index', 'Conversejs', u'Converse Documentation',
|
||||||
u'JC Brand', 'Conversejs', 'Open Source XMPP webchat',
|
u'JC Brand', 'Converse', 'Open Source XMPP webchat',
|
||||||
'Miscellaneous'),
|
'Miscellaneous'),
|
||||||
]
|
]
|
||||||
|
|
||||||
|
@ -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>
|
<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.
|
.. note:: The API documented here is available in Converse 0.8.4 and higher.
|
||||||
Earlier versions of Converse.js might have different API methods or none at all.
|
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
|
.. 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
|
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
|
access it. This change is done to avoid leakage of sensitive data to
|
||||||
malicious or non-whitelisted scripts.
|
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``).
|
example ``converse.plugins`` or ``converse.contacts``).
|
||||||
|
|
||||||
There are some exceptions to this, like ``converse.initialize``, which aren't
|
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.
|
.. 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.
|
Publich API method which initializes Converse.
|
||||||
This method must always be called when using converse.js.
|
This method must always be called when using Converse.
|
||||||
|
|
||||||
The `initialize` method takes a map of :ref:`configuration-settings`.
|
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
|
// Inside this method, you have access to the closured
|
||||||
// _converse object, which contains the core logic and data
|
// _converse object, which contains the core logic and data
|
||||||
// structures of converse.js
|
// structures of Converse
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
converse.plugins.add('myplugin', plugin);
|
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
|
* A handler registered for a promise, will still fire *after* the promise has
|
||||||
been resolved, which is not the case with an event handler.
|
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:`cachedRoster`
|
||||||
* :ref:`chatBoxesFetched`
|
* :ref:`chatBoxesFetched`
|
||||||
@ -210,7 +210,7 @@ already by that time.
|
|||||||
The **archive** grouping
|
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,
|
(`XEP-0313 <https://xmpp.org/extensions/xep-0313.html>`_) protocol,
|
||||||
through which it is able to query an XMPP server for archived messages.
|
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**
|
**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:
|
the server supports MAM queries, otherwise the following error will be raised:
|
||||||
|
|
||||||
- *This server does not support XEP-0313, Message Archive Management*
|
- *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
|
API too quickly, the above error might appear because service discovery has not
|
||||||
yet been completed.
|
yet been completed.
|
||||||
|
|
||||||
@ -453,7 +453,7 @@ Paramters:
|
|||||||
get
|
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
|
.. code-block:: javascript
|
||||||
|
|
||||||
@ -473,17 +473,17 @@ Paramters:
|
|||||||
* (String) name
|
* (String) name
|
||||||
* (String) lang
|
* (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
|
.. code-block:: javascript
|
||||||
|
|
||||||
_converse.api.disco.own.identities.add('client', 'web', 'Converse.js');
|
_converse.api.disco.own.identities.add('client', 'web', 'Converse');
|
||||||
|
|
||||||
|
|
||||||
get
|
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
|
.. 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
|
to log the user in by calling the `prebind_url` or `credentials_url` depending
|
||||||
on whether prebinding is used or not.
|
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
|
The **chatviews** grouping
|
||||||
--------------------------
|
--------------------------
|
||||||
|
|
||||||
@ -941,7 +907,7 @@ To return an array of views, provide an array of JIDs:
|
|||||||
The **listen** grouping
|
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"
|
Concerning events, the following methods are available under the "listen"
|
||||||
grouping:
|
grouping:
|
||||||
@ -1139,7 +1105,7 @@ JIDs.
|
|||||||
The **promises** grouping
|
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`.
|
:ref:`listen-grouping`.
|
||||||
|
|
||||||
Some of these events are also available as `ES2015 Promises <http://es6-features.org/#PromiseUsage>`_,
|
Some of these events are also available as `ES2015 Promises <http://es6-features.org/#PromiseUsage>`_,
|
||||||
@ -1198,7 +1164,7 @@ For example:
|
|||||||
The **settings** grouping
|
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`:
|
.. _`settings-update`:
|
||||||
|
|
||||||
@ -1279,7 +1245,7 @@ or :
|
|||||||
});
|
});
|
||||||
|
|
||||||
Note, this is not an alternative to calling ``converse.initialize``, which still needs
|
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.
|
running and you want to change the configuration on-the-fly.
|
||||||
|
|
||||||
The **tokens** grouping
|
The **tokens** grouping
|
||||||
|
@ -8,13 +8,13 @@
|
|||||||
Development
|
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
|
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
|
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::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
@ -22,6 +22,7 @@ or add new functionality to converse.js.
|
|||||||
developer_guidelines
|
developer_guidelines
|
||||||
style_guide
|
style_guide
|
||||||
plugin_development
|
plugin_development
|
||||||
|
api/index
|
||||||
developer_api
|
developer_api
|
||||||
events
|
events
|
||||||
other_frameworks
|
other_frameworks
|
||||||
|
@ -873,6 +873,11 @@
|
|||||||
|
|
||||||
/************************ BEGIN API ************************/
|
/************************ BEGIN API ************************/
|
||||||
_.extend(_converse.api, {
|
_.extend(_converse.api, {
|
||||||
|
/**
|
||||||
|
* The "chats" grouping (used for one-on-one chats)
|
||||||
|
*
|
||||||
|
* @namespace
|
||||||
|
*/
|
||||||
'chats': {
|
'chats': {
|
||||||
'create' (jids, attrs) {
|
'create' (jids, attrs) {
|
||||||
if (_.isUndefined(jids)) {
|
if (_.isUndefined(jids)) {
|
||||||
@ -882,7 +887,6 @@
|
|||||||
);
|
);
|
||||||
return null;
|
return null;
|
||||||
}
|
}
|
||||||
|
|
||||||
if (_.isString(jids)) {
|
if (_.isString(jids)) {
|
||||||
if (attrs && !_.get(attrs, 'fullname')) {
|
if (attrs && !_.get(attrs, 'fullname')) {
|
||||||
attrs.fullname = _.get(_converse.api.contacts.get(jids), 'attributes.fullname');
|
attrs.fullname = _.get(_converse.api.contacts.get(jids), 'attributes.fullname');
|
||||||
@ -899,6 +903,40 @@
|
|||||||
return _converse.chatboxes.getChatBox(jid, attrs, true).trigger('show');
|
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) {
|
'open' (jids, attrs) {
|
||||||
return new Promise((resolve, reject) => {
|
return new Promise((resolve, reject) => {
|
||||||
Promise.all([
|
Promise.all([
|
||||||
@ -917,6 +955,28 @@
|
|||||||
}).catch(_.partial(_converse.log, _, Strophe.LogLevel.FATAL));
|
}).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) {
|
'get' (jids) {
|
||||||
if (_.isUndefined(jids)) {
|
if (_.isUndefined(jids)) {
|
||||||
const result = [];
|
const result = [];
|
||||||
|
Loading…
Reference in New Issue
Block a user