Issue #2195183 by cleaver, zopa, elgordogrande, sandykadam, jhodgdon, joachim, Eda: document Batch API callbacks as callback implementations

8 files changed, 60 insertions, 9 deletions

diff --git a/modules/node/node.admin.inc b/modules/node/node.admin.inc
index 35f4c1d5b..145be7ad9 100644
--- a/modules/node/node.admin.inc
+++ b/modules/node/node.admin.inc
@@ -329,6 +329,8 @@ function _node_mass_update_helper($nid, $updates) {
 }
 
 /**
+ * Implements callback_batch_operation().
+ *
  * Executes a batch operation for node_mass_update().
  *
  * @param array $nodes
@@ -367,7 +369,9 @@ function _node_mass_update_batch_process($nodes, $updates, &$context) {
 }
 
 /**
- * Menu callback: Reports the status of batch operation for node_mass_update().
+ * Implements callback_batch_finished().
+ *
+ * Reports the status of batch operation for node_mass_update().
  *
  * @param bool $success
  *   A boolean indicating whether the batch mass update operation successfully
diff --git a/modules/node/node.module b/modules/node/node.module
index 7a6246d5a..f892d1c2c 100644
--- a/modules/node/node.module
+++ b/modules/node/node.module
@@ -3669,6 +3669,8 @@ function node_access_rebuild($batch_mode = FALSE) {
 }
 
 /**
+ * Implements callback_batch_operation().
+ *
  * Performs batch operation for node_access_rebuild().
  *
  * This is a multistep operation: we go through all nodes by packs of 20. The
@@ -3707,6 +3709,8 @@ function _node_access_rebuild_batch_operation(&$context) {
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * Performs post-processing for node_access_rebuild().
  *
  * @param bool $success
diff --git a/modules/simpletest/simpletest.module b/modules/simpletest/simpletest.module
index a98e5cfbe..29a20bb4c 100644
--- a/modules/simpletest/simpletest.module
+++ b/modules/simpletest/simpletest.module
@@ -154,7 +154,7 @@ function simpletest_run_tests($test_list, $reporter = 'drupal') {
 }
 
 /**
- * Batch operation callback.
+ * Implements callback_batch_operation().
  */
 function _simpletest_batch_operation($test_list_init, $test_id, &$context) {
   simpletest_classloader_register();
@@ -205,6 +205,9 @@ function _simpletest_batch_operation($test_list_init, $test_id, &$context) {
   $context['finished'] = 1 - $size / $max;
 }
 
+/**
+ * Implements callback_batch_finished().
+ */
 function _simpletest_batch_finished($success, $results, $operations, $elapsed) {
   if ($success) {
     drupal_set_message(t('The test run finished in @elapsed.', array('@elapsed' => $elapsed)));
diff --git a/modules/simpletest/tests/batch_test.callbacks.inc b/modules/simpletest/tests/batch_test.callbacks.inc
index 75e665533..6564413dd 100644
--- a/modules/simpletest/tests/batch_test.callbacks.inc
+++ b/modules/simpletest/tests/batch_test.callbacks.inc
@@ -7,6 +7,8 @@
  */
 
 /**
+ * Implements callback_batch_operation().
+ *
  * Simple batch operation.
  */
 function _batch_test_callback_1($id, $sleep, &$context) {
@@ -20,6 +22,8 @@ function _batch_test_callback_1($id, $sleep, &$context) {
 }
 
 /**
+ * Implements callback_batch_operation().
+ *
  * Multistep batch operation.
  */
 function _batch_test_callback_2($start, $total, $sleep, &$context) {
@@ -53,6 +57,8 @@ function _batch_test_callback_2($start, $total, $sleep, &$context) {
 }
 
 /**
+ * Implements callback_batch_operation().
+ *
  * Simple batch operation.
  */
 function _batch_test_callback_5($id, $sleep, &$context) {
@@ -68,6 +74,8 @@ function _batch_test_callback_5($id, $sleep, &$context) {
 }
 
 /**
+ * Implements callback_batch_operation().
+ *
  * Batch operation setting up its own batch.
  */
 function _batch_test_nested_batch_callback() {
@@ -76,6 +84,8 @@ function _batch_test_nested_batch_callback() {
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * Common 'finished' callbacks for batches 1 to 4.
  */
 function _batch_test_finished_helper($batch_id, $success, $results, $operations) {
@@ -99,6 +109,8 @@ function _batch_test_finished_helper($batch_id, $success, $results, $operations)
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * 'finished' callback for batch 0.
  */
 function _batch_test_finished_0($success, $results, $operations) {
@@ -106,6 +118,8 @@ function _batch_test_finished_0($success, $results, $operations) {
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * 'finished' callback for batch 1.
  */
 function _batch_test_finished_1($success, $results, $operations) {
@@ -113,6 +127,8 @@ function _batch_test_finished_1($success, $results, $operations) {
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * 'finished' callback for batch 2.
  */
 function _batch_test_finished_2($success, $results, $operations) {
@@ -120,6 +136,8 @@ function _batch_test_finished_2($success, $results, $operations) {
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * 'finished' callback for batch 3.
  */
 function _batch_test_finished_3($success, $results, $operations) {
@@ -127,6 +145,8 @@ function _batch_test_finished_3($success, $results, $operations) {
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * 'finished' callback for batch 4.
  */
 function _batch_test_finished_4($success, $results, $operations) {
@@ -134,6 +154,8 @@ function _batch_test_finished_4($success, $results, $operations) {
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * 'finished' callback for batch 5.
  */
 function _batch_test_finished_5($success, $results, $operations) {
diff --git a/modules/update/update.authorize.inc b/modules/update/update.authorize.inc
index 6ddd2c53a..03d370494 100644
--- a/modules/update/update.authorize.inc
+++ b/modules/update/update.authorize.inc
@@ -97,7 +97,9 @@ function update_authorize_run_install($filetransfer, $project, $updater_name, $l
 }
 
 /**
- * Batch callback: Copies project to its proper place when authorized to do so.
+ * Implements callback_batch_operation().
+ *
+ * Copies project to its proper place when authorized to do so.
  *
  * @param string $project
  *   The canonical short name of the project being installed.
@@ -168,7 +170,9 @@ function update_authorize_batch_copy_project($project, $updater_name, $local_url
 }
 
 /**
- * Batch callback: Performs actions when the authorized update batch is done.
+ * Implements callback_batch_finished().
+ *
+ * Performs actions when the authorized update batch is done.
  *
  * This processes the results and stashes them into SESSION such that
  * authorize.php will render a report. Also responsible for putting the site
@@ -235,7 +239,9 @@ function update_authorize_update_batch_finished($success, $results) {
 }
 
 /**
- * Batch callback: Performs actions when the authorized install batch is done.
+ * Implements callback_batch_finished().
+ *
+ * Performs actions when the authorized install batch is done.
  *
  * This processes the results and stashes them into SESSION such that
  * authorize.php will render a report. Also responsible for putting the site
diff --git a/modules/update/update.fetch.inc b/modules/update/update.fetch.inc
index 9dd2f0ba4..428cace6b 100644
--- a/modules/update/update.fetch.inc
+++ b/modules/update/update.fetch.inc
@@ -29,7 +29,9 @@ function update_manual_status() {
 }
 
 /**
- * Batch callback: Processes a step in batch for fetching available update data.
+ * Implements callback_batch_operation().
+ *
+ * Processes a step in batch for fetching available update data.
  *
  * @param $context
  *   Reference to an array used for Batch API storage.
@@ -77,7 +79,9 @@ function update_fetch_data_batch(&$context) {
 }
 
 /**
- * Batch callback: Performs actions when all fetch tasks have been completed.
+ * Implements callback_batch_finished().
+ *
+ * Performs actions when all fetch tasks have been completed.
  *
  * @param $success
  *   TRUE if the batch operation was successful; FALSE if there were errors.
diff --git a/modules/update/update.manager.inc b/modules/update/update.manager.inc
index 85b587de2..0b33a5f72 100644
--- a/modules/update/update.manager.inc
+++ b/modules/update/update.manager.inc
@@ -335,6 +335,8 @@ function update_manager_update_form_submit($form, &$form_state) {
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * Batch callback: Performs actions when the download batch is completed.
  *
  * @param $success
@@ -847,7 +849,9 @@ function update_manager_file_get($url) {
 }
 
 /**
- * Batch callback: Downloads, unpacks, and verifies a project.
+ * Implements callback_batch_operation().
+ *
+ * Downloads, unpacks, and verifies a project.
  *
  * This function assumes that the provided URL points to a file archive of some
  * sort. The URL can have any scheme that we have a file stream wrapper to
diff --git a/modules/user/user.module b/modules/user/user.module
index 6a742c8e6..afb411998 100644
--- a/modules/user/user.module
+++ b/modules/user/user.module
@@ -2488,7 +2488,9 @@ function user_cancel($edit, $uid, $method) {
 }
 
 /**
- * Last batch processing step for cancelling a user account.
+ * Implements callback_batch_operation().
+ *
+ * Last step for cancelling a user account.
  *
  * Since batch and session API require a valid user account, the actual
  * cancellation of a user account needs to happen last.
@@ -2536,6 +2538,8 @@ function _user_cancel($edit, $account, $method) {
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * Finished batch processing callback for cancelling a user account.
  *
  * @see user_cancel()