Improve batch_process() documentation

I've added a couple of tags. This could use a little investigation to improve the issue summary to outline the changes before starting on the patch.

Added documentation to the batch_process() function to further detail what happens when falsey values are passed as the redirect parameter.

@philipnorton42 - what about further elaboration using the *Proposed resolution* above? I'm struggling to make sense of those docs generally, and to me it seems that the two lines you've added is simply restating what was said in the lines above.

Maybe my general understanding is lacking in the first place?

@siliconmeadow - You are correct. Now you point it out what I've added does not add value.

I think this issue has been created to show users who are familiar with batch processing in Drupal 7 that they should be aware that it's a little bit different in Drupal 8. As such it might be best change it to the following

/**
 * Processes the batch.
 *
 * This function is generally not needed in form submit handlers;
 * Form API takes care of batches that were set during form submission.
 *
 * @param \Drupal\Core\Url|string $redirect
 *   (optional) Either path or Url object to redirect to when the batch has
 *   finished processing. Note that to simply force a batch to (conditionally)
 *   redirect to a custom location after it is finished processing but to
 *   otherwise allow the standard form API batch handling to occur, it is not
 *   necessary to call batch_process() and use this parameter. Instead, make
 *   the batch 'finished' callback return an instance of
 *   \Symfony\Component\HttpFoundation\RedirectResponse, which will be used
 *   automatically by the standard batch processing pipeline (and which takes
 *   precedence over this parameter).
 *   User will be redirected to the page that started the batch if this argument
 *   is omitted and no redirect response was returned by the 'finished'
 *   callback. Any query arguments will be automatically persisted.
 *   In previous versions of Drupal omitting this value would return the user to
 *   the home page. To replicate this functionality batch_process('<front>') 
 *   should be used.
 * @param \Drupal\Core\Url $url
 *   (optional) URL of the batch processing page. Should only be used for
 *   separate scripts like update.php.
 * @param $redirect_callback
 *   (optional) Specify a function to be called to redirect to the progressive
 *   processing page.
 *
 * @return \Symfony\Component\HttpFoundation\RedirectResponse|null
 *   A redirect response if the batch is progressive. No return value otherwise.
 */

That would seem to be a better way to explain the differences.

Speaking to @john-cook we think it might be better not to mention the difference between D7 and D8 and just state what to do if you want to send the user to the home page.

As a result, maybe this might be a better way to word the functionality:

To return the user to the home page use batch_process('<front>').

Updating patch with latest wording.

Looks good to me

Here is the patch which fixes #13.

Latest patch appears to reflow a paragraph that's further down.

I am not sure if @param description can have multiple paragraphs. I thought it should have only one paragraph in the description that is why I moved that paragraph to up.

Hello. I found the "Note that to simply force a batch to..." sentence a bit difficult to follow. Please see the attached patch which rewrites that sentence and has some other minor changes to smooth out the wording, while retaining the information.

Thanks! I agree, the 'note that' was a little hard to follow; this makes it clearer.

Just one thing:

+++ b/core/includes/form.inc
@@ -792,18 +792,18 @@ function batch_set($batch_definition) {
+ *   ‘<front>’. If you wish to allow standard form API batch handling to occur
...
+ *   parameter. Instead, make the batch ‘finished’ callback return an instance
...
+ *   redirect response was returned by the ‘finished’ callback, the user will

These should be straight quotes, not smart quotes.

Thanks for taking a look, @joachim. Here is a new patch with the smart quotes converted to straight quotes. (Also...I find dorgflow very useful!)

I think this looks good.

(Great to hear that dorgflow is useful to people, thanks!!)

Committed and pushed 34b94c8c3a to 8.7.x and 8f75b2aacc to 8.6.x. Thanks!