Document Batch API callbacks

What this issue is about: we now have standards (see link above) for documenting callback function signatures.

So what we need to do is look at the Batch API functions in Drupal 8 and 7, and see if they require the caller to pass in functions with a particular signature; if so, define them as callback_batch_foo() in system.api.php and then amend the batch function documentation to refer to them (see standards link above).

Might be a good novice project?

You can do something like:

@param ...
   Additional parameters specific to the batch.
@param $context

Um, yes. They need to have valid PHP in them, or the API module will not be able to parse them.

How about something like this:

/**
...
 * @param $params
 *   Each specific callback can have zero or more parameters specific to
 *   the operation. These are specified in the array passed to batch_set(), and
 *   in the example function below, are represented by $params, although it
 *   could be any number of individual parameters.
...
function callback_batch_operation($params, &$context) {

I think that is a reasonable way to document this function.

So... This is nearly ready to go. A few things I noticed:

a) Our callback standards:
https://drupal.org/node/1354#callback-def
say we're supposed to have a line like

 *
* Callback for batch_set().

in the callback function docs. This is missing from both of the callbacks.

b)

+ *     be called again, and execution passes to the next operation or the
+ *     finished callback. Any other value causes this operation to be called

"finished callback"... Should that be callback_batch_finished()? or at least be in quotes or something?

c)

+ *     finished callback. Any other value causes this operation to be called
+ *     again, however it should be noted that the value set here does not

before "however" it should be ; not ,

d)

 *   - 'sandbox': This may be used by operations to persist data between
+ *     successive calls to the current operation. For example, an operation may
+ *     which to store a pointer in a file or an offset for a large query. This
+ *     array key is not initially set when this callback is first called, which makes it useful for determining
+ *     whether it is the first run or not:

Um... Something got left out here? And that 2nd to last line is too long. Actually, the whole sandbox section doesn't make much sense to me.

e) callback_batch_finished() has no @param or @return docs. It may not need @return, but does have several parameters.

f) Doesn't the batch_set() documentation need to reference these new callback definitions?

Much better! I like all of the documentation, and I think the examples are very clear. The only thing that I wondered about was in the operations example, whether it would be clear that $option1 and $option2 local variables were supposed to be part of the parameters? Maybe a code comment at the top explaining this would be helpful?

Anyway, I guess we could commit this as it is... the only other thing that might be helpful though would be to update documentation for actual operations/finished callbacks in Core to reference this documentation. Which you can find by looking at api.drupal.org for who calls batch_set(). I wouldn't document the ones used it tests (kind of pointless) but maybe the others? Or we can just leave that out. Thoughts?

Fair enough. Let's just get this in then.

There's an "avoid commit conflicts" issue touching form.inc
#1996238: Replace hook_library_info() by *.libraries.yml file
so I'm going to be extra-cautious and wait to commit this until that's resolved, even though I am pretty sure there isn't a direct conflict with this patch.

I got leave from the other issue person to commit this, so it's committed to 8.x. The patch also worked OK for 7.x, so I committed it there too. Thanks again!