Add missing and fix some types in core docblocks and add some typehinting for locale module

Patch no longer applies. Tagging for reroll.

Here's the straight reroll. More detailed review to follow.

Rerolling #9 patch.

Under the help of mentor, we found few things need to be change.

In function locale_translation_batch_status_check(), the options array was optional but make un-optional. This change is not in the scope of the issue. Why it was needed to be made?

#10 patch add a blank before the @param bool $force in locale_translate_batch_import_files() , this is not standard. See doxygen reference: https://www.drupal.org/node/1354#order

[edit: to correct link]

Please review.

Looks great to me!

+++ b/core/modules/locale/locale.batch.inc
@@ -25,7 +25,7 @@
- *   Optional, an array with options that can have the following elements:
+ *   (optional) An array with options that can have the following elements:

@@ -33,7 +33,7 @@
-function locale_translation_batch_status_check($project, $langcode, $options = array(), &$context) {
+function locale_translation_batch_status_check($project, $langcode, array $options = array(), &$context) {

So this actually can not be optional since $context is mandatory and after it in the argument list. So let's remove the optional altogether. Plus $context can also be typehinted with array (as it is elsewhere in this patch)

Um...

+ *   An array with options that can have the following elements:
  *   - 'finish_feedback': Whether or not to give feedback to the user when the
  *     batch is finished. Optional, defaults to TRUE.
  *   - 'use_remote': Whether or not to check the remote translation file.
  *     Optional, defaults to TRUE.
+ *   Options can be an empty array, for example: array();.

That last line seems ... extraneous, because the elements each say they're optional, and I also don't think we need to tell people that "an empty array" is "for example: array()". If you think it's that important to include, then I think it should be worked into the first line of the param docs, not slapped onto the end where it's less likely to be noticed?

Also I'm concerned about:

-function locale_translation_batch_status_check($project, $langcode, $options = array(), &$context) {
+function locale_translation_batch_status_check($project, $langcode, array $options, array &$context) {

This used to have a default value of array() but now it doesn't?

Also we have a standard that if a parameter is optional, the first line of the description should say "(optional)".

And here:

+ * @return array|bool
+ *   The batch structure, or FALSE if no files used to build the batch.

This is missing the word "are"... if no files [ARE] used to...

The rest looks good...

I am on this.

Here's my attempt at updating the documentation based on the feedback provided. I added (optional) in front of finish_feedback and use_remote instead of having them at the end.

I've removed the last line saying options can be an empty array.

I'm going to take a couple things out of the patch and create a new issue for some of it as recommended by YesCT.

So... this issue is not really just documentation? perhaps change the component?

I've created a new issue for rearranging the order of the arguments in locale_translation_batch_status_check:

https://www.drupal.org/node/2359615

Here's the proposed patch. I've removed the documentation updates from locale_translation_batch_status_check as it needs some work in the issue that was just created regarding the argument reordering.

Sorry but I've just closed #2359615: function locale_translation_batch_status_check has an optional argument before a mandatory argument in the function definition and explained on that issue why reordering the arguments is not possible and why the $options argument can not possible be optional.

@alexpott: I apologize I misunderstood when creating that issue. I'll just change the component from documentation to locale.module and make the options argument no longer optional.

I've updated the options argument in locale_translation_batch_status_check so it is no longer optional and changed the documentation to reflect this. Here's the next patch.

Looks great to me. Thanks for sticking with it @jamesdixon.

+++ b/core/modules/locale/locale.batch.inc
@@ -25,7 +25,7 @@
  * @param array $options
- *   Optional, an array with options that can have the following elements:
+ *   An array with options that can have the following elements:

The $options argument is itself not actually optional because of how the batch system works. Both the elements it can contain are optional and that fact is documented.

Committed/pushed to 8.0.x, thanks!