batch_set has wrong name in @param doc

I don't think this chunk belongs in the patch:

--- a/core/includes/form.inc
+++ b/core/includes/form.inc
@@ -4370,7 +4370,7 @@ function element_validate_number($element, &$form_state) {
  *   'finished' => 'my_finished_callback',
  *   'file' => 'path_to_file_containing_myfunctions',
  * );
- * batch_set($batch);
+ * batch_set($batch_definition);

That is part of a code example, and the variable above there is definitely $batch, so that needs to stay as it was.

Regarding the other changes... If you want to bring the whole function up to coding standards (which is always nice!), you might also want to fix this bit:

 * @param $batch_definition
  *   An array defining the batch. The following keys can be used -- only
  *   'operations' is required, and batch_init() provides default values for
  *   the messages.

It should probably say something more like:

An associative array defining the batch, with the following elements (all optional except where noted):

And then the list below should use (required) on that one required element.

Also, the paragraph at the end... If it is part of the @param, then there should not be a blank line before it. If it is not part of the @param, then it should be moved up to before the @param section of the docs.

Much better!

So... I know you didn't write these parts, but what do you think about the following ideas to further improve this documentation:

a) In the top paragraph, explaining about batches, it says:

Batch operations are added as new batch sets. Batch sets are used to provide clean code independence, ...

But really, I think the main reason we use batches is not to provide independence, but to process things that might take a while, right? That is not really explained anywhere, so it might be good to add something basic about the purpose of batches to that paragraph.

b) In the 'title' list item, it says: "Only safe strings should be passed." ... I always suggest this wording be changed whenever I see it in @param documentation. It should at least say "passed in", or better yet reword the whole list item to something like:

title: A safe, translated string to use as the title for the progress page. Defaults to t('Processing').

Other than those two suggestions, this looks good! Thanks!

I think this looks great, thanks! I'll get it committed when I get back to my main computer (probably tomorrow),.

I committed this to 8.x. Needs port to 7.x.

This is now in 7.x too. Thanks!

And by the way, don't be alarmed about the test failure in #5. The test had stalled due to something weird on qa.drupal.org, and it finally got run after I had committed the patch, which is why it couldn't be applied.