Issue #3018774 by xjm: hook_post_update_NAME() docs do not explain batching/ parameter

(cherry picked from commit a9472244bf827f1e6549e9edb6997bd508d4bd16)

core/lib/Drupal/Core/Extension/module.api.php

@@ -684,6 +684,20 @@ function hook_update_N(&$sandbox) {
  * Drupal also ensures to not execute the same hook_post_update_NAME() function
  * twice.
  *
+ * @section sec_bulk Batch updates
+ * If running your update all at once could possibly cause PHP to time out, use
+ * the $sandbox parameter to indicate that the Batch API should be used for your
+ * update. In this case, your update function acts as an implementation of
+ * callback_batch_operation(), and $sandbox acts as the batch context
+ * parameter. In your function, read the state information from the previous
+ * run from $sandbox (or initialize), run a chunk of updates, save the state in
+ * $sandbox, and set $sandbox['#finished'] to a value between 0 and 1 to
+ * indicate the percent completed, or 1 if it is finished (you need to do this
+ * explicitly in each pass).
+ *
+ * See the @link batch Batch operations topic @endlink for more information on
+ * how to use the Batch API.
+ *
  * @param array $sandbox
  *   Stores information for batch updates. See above for more information.
  *