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

includes/install.core.inc

@@ -1590,7 +1590,9 @@ function install_finished(&$install_state) {
 }
 
 /**
- * Batch callback for batch installation of modules.
+ * Implements callback_batch_operation().
+ *
+ * Performs batch installation of modules.
  */
 function _install_module_batch($module, $module_name, &$context) {
   // Install and enable the module right away, so that the module will be
@@ -1603,6 +1605,8 @@ function _install_module_batch($module, $module_name, &$context) {
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * 'Finished' callback for module installation batch.
  */
 function _install_profile_modules_finished($success, $results, $operations) {

includes/locale.inc

@@ -2306,6 +2306,8 @@ function _locale_batch_build($files, $finished = NULL, $components = array()) {
 }
 
 /**
+ * Implements callback_batch_operation().
+ *
  * Perform interface translation import as a batch step.
  *
  * @param $filepath
@@ -2324,6 +2326,8 @@ function _locale_batch_import($filepath, &$context) {
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * Finished callback of system page locale import batch.
  * Inform the user of translation files imported.
  */
@@ -2334,6 +2338,8 @@ function _locale_batch_system_finished($success, $results) {
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * Finished callback of language addition locale import batch.
  * Inform the user of translation files imported.
  */

includes/update.inc

@@ -908,6 +908,8 @@ function update_get_d6_session_name() {
 }
 
 /**
+ * Implements callback_batch_operation().
+ *
  * Performs one update and stores the results for display on the results page.
  *
  * If an update function completes successfully, it should return a message
@@ -1078,6 +1080,8 @@ function update_batch($start, $redirect = NULL, $url = NULL, $batch = array(), $
 }
 
 /**
+ * Implements callback_batch_finished().
+ *
  * Finishes the update process and stores the results for eventual display.
  *
  * After the updates run, all caches are flushed. The update results are

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

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

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)));

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) {

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

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.

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

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()