diff --git a/nodequeue.api.php b/nodequeue.api.php
index 6a16b2c..dbbc63d 100644
--- a/nodequeue.api.php
+++ b/nodequeue.api.php
@@ -1,52 +1,67 @@
 <?php
 
 /**
- * Triggered when a node is added to a subqueue.
+ * Triggered when a node is added to a sub-queue, after adding the sub-queue.
+ *
+ * This hook is invoked after the update has been sent to apachesolr module, if
+ * it is enabled.
  *
  * @param int $qid
- *   The subqueue id.
+ *   The sub-queue id.
  * @param int $nid
  *   The node id
+ *
+ * @see nodequeue_subqueue_add()
  */
 function hook_nodequeue_add($qid, $nid) {
-  // Invoked from:
-  nodequeue_subqueue_add($queue, $subqueue);
 }
 
 /**
- * Triggered when nodes are removed from a subqueue.
+ * Triggered when nodes are removed from a sub-queue.
  *
- * This is invoked in a loop for all removed nodes.
+ * This is invoked in a loop for all removed nodes, after the queue has been
+ * updated.
  *
  * @param int $qid
  *   The subqueue id.
  * @param int $nid
  *   The node id
+ *
+ * @see nodequeue_subqueue_remove()
  */
 function hook_nodequeue_remove($qid, $nid) {
-  // Invoked from:
-  nodequeue_subqueue_remove();
 }
 
 /**
- * Triggered when a node changes position within a subqueue.
+ * Triggered when a node changes position within a sub-queue, after the swap.
  *
  * @param int $qid
  *   The subqueue id.
  * @param int $nid
  *   The node id
+ *
+ * @see nodequeue_queue_swap()
  */
 function hook_nodequeue_swap($qid, $nid) {
-  // Invoked from:
-  nodequeue_queue_swap();
 }
 
 /**
  * Expose nodequeue info.
+ *
+ * @see nodequeue_api_info()
  */
 function hook_nodequeue_info() {
-  // Invoked from:
-  nodequeue_api_info();
+  // This example show how the built-in queues are declared.
+  return array(
+    'nodequeue' => array(
+      'title' => t('Simple queue'),
+      'description' => t('Simple queues have just one subqueue. Nodes put into a queue are added to the back of the queue; when a node is added to a full queue, the node in the front of the queue will be popped out to make room.'),
+    ),
+    'smartqueue_taxonomy' => array(
+      'title' => t('Taxonomy queue'),
+      'description' => t('Each particular grouping of taxonomy terms from the selected vocabularies have their own unique subqueue. You can place nodes into any of these subqueues based on which terms that node has been tagged with. Using this with large or too many taxonomies may degrade performance.'),
+    ),
+  );
 }
 
 /**
@@ -56,18 +71,18 @@ function hook_nodequeue_info() {
  *
  * @param array $nodes
  * @param int $sqid
+ *
+ * @see nodequeue_save_subqueue_order()
  */
 function hook_nodequeue_sort_alter($nodes, $sqid) {
-  // Invoked from:
-  nodequeue_save_subqueue_order();
 }
 
 /**
  * Allow altering a node reordering action.
  *
  * This is called after validation has been performed and nodes removed, but
- * before the new order of the queue is saved. This is the last nodequeue hook
- * in a reorder operation.
+ * before the new order of the queue is saved. This is the next-before-last
+ * nodequeue hook in a reorder operation, the last being hook_nodequeue_update.
  *
  * @param array $nodes
  * @param int $sqid
@@ -78,122 +93,166 @@ function hook_nodequeue_save_subqueue_order_alter($qid, $nodes) {
 }
 
 /**
- * Allow modules to react to a queue deletion.
+ * Allow modules to react to a node reordering action.
+ *
+ * This is the last hook in a reordering, after hook_nodequeue_sort_alter() and
+ * hook_nodequeue_save_subqueue_order_alter().
  *
- * @since After 7.x-2.0-beta1.
+ * @param mixed $qid
+ *   The queue being reordered.
+ * @param mixed $s_qid
+ *   The sub-queue being reordered.
+ *
+ * @see nodequeue_save_subqueue_order()
+ *
+ * @since After 7.x-2.0.
+ */
+function hook_nodequeue_update($qid, $s_qid) {
+
+}
+
+/**
+ * Allow modules to react to a queue deletion.
  *
  * @param int $qid
+ *   The id of the queue for which deletion was attempted.
+ * @param array|object
+ *   An object containing the deleted queue, if found, an empty array otherwise.
+ *
+ * @see nodequeue_delete()
+ *
+ * @since After 7.x-2.0-beta, with just a qid
+ * @since After commit dd1f758 with the $queue parameter.
  */
 function hook_nodequeue_delete($qid) {
-  // Invoked from:
-  nodequeue_delete();
 }
 
 /**
  * Allow altering the queue edit form.
  *
- * @param stdClass $queue
+ * This hook is actually a callback for the module defining the queue instead
+ * of a generic hook.
+ *
+ * @param object $queue
+ *   A queue being edited.
  * @param array $form
+ *   The form array to edit the queue.
+ *
+ * @see nodequeue_api_queue_form()
  */
-function hook_nodequeue_form($queue, $form) {
-  // Invoked from:
-  nodequeue_api_queue_form();
+function hook_nodequeue_form($queue, &$form) {
 }
 
 /**
  * Allow validating the queue edit form.
  *
- * @param stdClass $queue
+ * This hook is actually a callback for the module defining the queue instead
+ * of a generic hook.
+ *
+ * @param object $queue
  * @param array $form_state
  * @param array $form
+ *
+ * @see nodequeue_api_queue_form_validate()
  */
 function hook_nodequeue_form_validate($queue, $form_state, $form) {
-  // Invoked from:
-  nodequeue_api_queue_form_validate();
 }
 
 /**
  * Allow submitting the queue edit form. First pass.
  *
- * @param stdClass $queue
+ * This hook is actually a callback for the module defining the queue instead
+ * of a generic hook.
+ *
+ * @param object $queue
  * @param array $form_state
+ *
+ * @see nodequeue_api_queue_form_submit()
  */
 function hook_nodequeue_form_submit($queue, $form_state) {
-  // Invoked from:
-  nodequeue_api_queue_form_submit();
 }
 
 /**
  * Allow submitting the queue edit form. Second pass.
  *
+ * This hook is actually a callback for the module defining the queue instead
+ * of a generic hook.
+ *
  * @param stdClass $queue
  * @param array $form_state
+ *
+ * @see nodequeue_api_queue_form_submit()
  */
 function hook_nodequeue_form_submit_finish($queue, $form_state) {
-  // Invoked from:
-  nodequeue_api_queue_form_submit_finish();
 }
 
 /**
- * Allow providing a list of subqueues valid for a node within a queue.
+ * Allow providing a list of valid sub-queues for a node within a queue.
+ *
+ * This hook is actually a callback for the module defining the queue instead
+ * of a generic hook.
  *
  * @param stdClass $queue
  * @param stdClass $node
  *   A fully loaded node object
+ *
+ * @see nodequeue_api_subqueues()
  */
 function hook_nodequeue_subqueues($queue, $node) {
-  // Invoked from:
-  nodequeue_api_subqueues();
 }
 
 /**
- * Provide an alternative way to provide autocomplete results.
+ * Provide an alternative way to provide auto-complete results.
  *
  * If this hook is implemented, the builtin query in nodequeue is not used, and
  * the results from this hook are returned instead.
  *
- * @param stdClass $queue
- * @param stdClass $subqueue
+ * This hook is actually a callback for the module defining the queue instead
+ * of a generic hook.
+ *
+ * @param object $queue
+ * @param object $subqueue
  * @param string $string
- * @param undefined $where
- *   This looks like a bug in nodequeue: this variable is neither initialized
- *   nor used. It uses $query->where, but passes $where to this hook.
- * @param array $where_args
- *   This looks like a bug in nodequeue: this variable is passed as an empty
- *   array, and unused after this hook.
- */
-function hook_nodequeue_autocomplete($queue, $subqueue, $string, $where, $where_args) {
-  // Invoked from:
-  nodequeue_api_autocomplete();
+ * @param object $query
+ *
+ * @see nodequeue_api_autocomplete()
+ */
+function hook_nodequeue_autocomplete($queue, $subqueue, $string, $query) {
 }
 
 /**
  * Provide queue access control.
  *
+ * This hook is actually a callback for the module defining the queue instead
+ * of a generic hook.
+ *
  * @param stdClass $queue
  * @param stdClass $account
  *
  * @return NULL|TRUE|FALSE
- *   NULL and TRUE grant access. FALSE refuses it.
+ *   NULL and TRUE grant access. FALSE rejects it.
+ *
+ * @see nodequeue_api_queue_access()
  */
 function hook_queue_access($queue, $account) {
-  // Invoked from:
-  nodequeue_api_queue_access();
 }
 
 /**
- * Provide subqueue access control.
+ * Provide sub-queue access control.
  *
- * @param stdClass $queue
+ * This hook is actually a callback for the module defining the queue instead
+ * of a generic hook.
+ *
+ * @param stdClass $sub_queue
  * @param stdClass $account
- * @param stdClass $subqueue
+ * @param stdClass $queue
  *
  * @return NULL|TRUE|FALSE
  *   NULL and TRUE grant access. FALSE refuses it.
+ *
+ * @see nodequeue_api_subqueue_access()
  */
-function hook_subqueue_access($subqueue, $account, $queue) {
-  // Invoked from:
-  nodequeue_api_subqueue_access();
+function hook_subqueue_access($sub_queue, $account, $queue) {
 }
 
 /**
@@ -202,11 +261,10 @@ function hook_subqueue_access($subqueue, $account, $queue) {
  * @param array $loaded
  *   A qid-indexed hash of queues
  * @param string $context
- *   This looks like a historical artefact: this hook receives the constant
- *   string 'load_queues' in this parameter, and its value is unused by the
- *   caller.
+ *   This hook receives the constant string 'load_queues' in this parameter, and
+ *   its value is unused by the caller afterwards.
+ *
+ * @see nodequeue_load_queues()
  */
 function hook_nodequeue_alter($loaded, $context) {
-  // Invoked from:
-  nodequeue_load_queues();
 }