hook_batch_alter() is undocumented

Of course this needs review

Actually, no, heyrocker left it as "needs work" because there is no function body (read original posting).

Ok i'm srry

No problem. Want to take a stab at writing the function body? :)

Nop I just ordered drupal pro development 3 in pre release. Maybe when I finished the book ;)

Is this a good example of its use?

http://api.drupal.org/api/function/overlay_batch_alter/7

Good find! Yes indeed. :)

This might help as well, it has a list of possible keys for $batch

batch_set: http://api.drupal.org/api/function/batch_set/7

I'm new here, so please correct me if I'm wrong about this, but I think we can use the same list of keys without any change in the wording.

OK, here's a patch with a function body, taken from overlay.module() as suggested above.

It looks like maybe you just edited the patch instead of applying, editing, doing the diff again and the line numbers are confused, so the patch format is invalid?

Going back to my comment in #10, do we need to work in this list of keys for $batch?
Here is what I found from batch set:

 @param $batch
 *   An array defining the batch. The following keys can be used -- only
 *   'operations' is required, and batch_init() provides default values for
 *   the messages.
 *  - 'operations': Array of function calls to be performed.
 *     Example:
 *     @code
 *     array(
 *       array('my_function_1', array($arg1)),
 *       array('my_function_2', array($arg2_1, $arg2_2)),
 *     )
 *     @endcode
 *   - 'title': Title for the progress page. Only safe strings should be passed.
 *     Defaults to t('Processing').
 *   - 'init_message': Message displayed while the processing is initialized.
 *     Defaults to t('Initializing.').
 *   - 'progress_message': Message displayed while processing the batch.
 *     Available placeholders are @current, @remaining, @total, @percentage,
 *     @estimate and @elapsed. Defaults to t('Completed @current of @total.').
 *   - 'error_message': Message displayed if an error occurred while processing
 *     the batch. Defaults to t('An error has occurred.').
 *   - 'finished': Name of a function to be executed after the batch has
 *     completed. This should be used to perform any result massaging that
 *     may be needed, and possibly save data in $_SESSION for display after
 *     final page redirection.
 *   - 'file': Path to the file containing the definitions of the
 *     'operations' and 'finished' functions, for instance if they don't
 *     reside in the main .module file. The path should be relative to
 *     base_path(), and thus should be built using drupal_get_path().
 *   - 'css': Array of paths to CSS files to be used on the progress page.
 *   - 'url_options': options passed to url() when constructing redirect
 *     URLs for the batch.

One thing to note, the function actually calls the argument batch_definition, but then the docs use $batch.

A good point about having more detail... but maybe instead of documenting it we could just say explicitly that the array being modified is the input to batch_set() or see batch_set() for a list of what the array might contain, or something like that?

Not sure about your last comment trevjs, though. It looks like the whole doc is consistently using $batch.

I don't think we need to list all the possibilities here, since this hook is just allowing modules to alter the batch information anyway....

How about just

+ *   The associative array of batch information. See batch_set() for details on what this could contain.

(with proper 80-character line wrapping).

Or something like that... maybe "contains" instead of "could contain"?

jhodgdon forced me to take this one.

Added sentence jhodgdon recommended. Ready for review.

Looks good to me.

Committed to HEAD! Thanks!