Even better docs

src/actions/GroupActions.js

@@ -19,12 +19,13 @@ import { asyncAction } from './actionCreators';
 const GroupActions = {};
 
 /**
- * Create a  GroupActions.fetchJoinedGroups action that represents an
- * asynchronous request to fetch the groups to which a user is joined.
+ * Creates an action thunk that will do an asynchronous request to fetch
+ * the groups to which a user is joined.
  *
  * @param {MatrixClient} matrixClient the matrix client to query.
- * @returns {function} an asynchronous action of type
- *                   GroupActions.fetchJoinedGroups.
+ * @returns {function} an action thunk that will dispatch actions
+ *                     indicating the status of the request.
+ * @see asyncAction
  */
 GroupActions.fetchJoinedGroups = function(matrixClient) {
     return asyncAction('GroupActions.fetchJoinedGroups', () => matrixClient.getJoinedGroups());

src/actions/TagOrderActions.js

@@ -21,14 +21,15 @@ import TagOrderStore from '../stores/TagOrderStore';
 const TagOrderActions = {};
 
 /**
- * Create a TagOrderActions.commitTagOrdering action that represents an
- * asyncronous request to commit TagOrderStore.getOrderedTags() to account
- * data.
+ * Creates an action thunk that will do an asynchronous request to
+ * commit TagOrderStore.getOrderedTags() to account data and dispatch
+ * actions to indicate the status of the request.
  *
- * @param {MatrixClient} matrixClient the matrix client to set the account
- *                                    data on.
- * @returns {function} an asynchronous action of type
- *                   TagOrderActions.commitTagOrdering.
+ * @param {MatrixClient} matrixClient the matrix client to set the
+ *                                    account data on.
+ * @returns {function} an action thunk that will dispatch actions
+ *                     indicating the status of the request.
+ * @see asyncAction
  */
 TagOrderActions.commitTagOrdering = function(matrixClient) {
     return asyncAction('TagOrderActions.commitTagOrdering', () => {

src/actions/actionCreators.js

@@ -15,14 +15,19 @@ limitations under the License.
 */
 
 /**
- * Create an asynchronous action creator that will dispatch actions indicating
- * the current status of the promise returned by fn.
+ * Create an action thunk that will dispatch actions indicating the current
+ * status of the Promise returned by fn.
+ *
  * @param {string} id the id to give the dispatched actions. This is given a
  *                    suffix determining whether it is pending, successful or
  *                    a failure.
  * @param {function} fn a function that returns a Promise.
- * @returns {function} an asynchronous action creator - a function that uses
- *                     its single argument as a dispatch function.
+ * @returns {function} an action thunk - a function that uses its single
+ *                     argument as a dispatch function to dispatch the
+ *                     following actions:
+ *                         `${id}.pending` and either
+ *                         `${id}.success` or
+ *                         `${id}.failure`.
  */
 export function asyncAction(id, fn) {
     return (dispatch) => {