Chapril/xmpp.chapril.org-conversejs
Chapril/xmpp.chapril.org-conversejs
25
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

Add jsdoc docstrings to chats API.

Browse Source 
Link to the jsdoc output from the Sphinx docs
This commit is contained in:
JC Brand 2018-08-01 12:08:18 +02:00
parent 506aa33131
commit dc4c832fce
5 changed files with 97 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Makefile
View File

@ -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."

16
docs/source/conf.py
View File

@ -1,6 +1,6 @@
# -*- 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'),
]

78
docs/source/developer_api.rst
View File

@ -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

9
docs/source/development.rst
View File

@ -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

62
src/converse-chatboxes.js
View File

@ -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 = [];