Add missing @param in includes D-G

Updated issue summary.

.

Updated issue summary.

Updated issue summary.

Updated issue summary.

Note that, as in #1326456: Add missing @param in includes A-C, plus other corrections to some docblocks, I added datatypes for the new parameters because it's necessary to look the function up anyway to see how the parameters are used.

To review this patch:

1. Review only the changed lines (lines with a + or - in front of them, not the other lines which are provided for context.)
2. Check that each parameter block is formatted correctly per http://drupal.org/node/1354#functions, including the correct indentation and the correct whitespace between the parameter list and other parts of the docblock.
3. Check that the parameters are identified correctly. For example, if the function signature is function($foo_bar), the parameter should be listed as $foo_bar in the docblock, not $foobar.
4. Check that all parameters are documented, unless our standards explicitly specify omitting them (as with form constructors).
5. Check that the parameters are in the order specified in the function signature.
6. Read each parameter description and make sure that it is grammatically correct, clear English, with proper capitalization, punctuation, etc. (Each parameter description should form a complete English sentence if the words "This parameter is..." were to be added to the beginning, but those words should not be included in the docblock.) Keep an eye out for typos.
7. Look up each function in the patch on api.drupal.org (D8). Read the function carefully and ensure that the parameter description properly documents how the parameter is used.
8. Look at the datatype documented for each parameter. Make sure the types correspond to the allowed types at http://drupal.org/node/1354#param-return-data-type.
9. Make sure all possibilities for the parameter are documented; for example, if the function optionally accepts a NULL value for a string parameter, then it should be documented as string|null.
10. Also check the function's callers and string references (linked on api.d.o) and make sure the values being passed to the function are in the datatypes specified.
11. Apply the patch to your local repository, and check that no other functions in these files are missing parameter documentation.
12. Document what you reviewed and what you found specifically in your review comment.

I also found a few places where variable references were made in some function when the accepted properties were defined.

Could you clarify this? Do you mean the chaos of random passing by reference versus not? I have that as a point for followup in the summary. Or something else?

Marking NW for #6. Thanks @hosef for the review!

.

'form_process_checkboxes' only accepts '$elements', it does not accept '$form_state'

Weird... this is rather different from the FAPI element functions. I'll add this to the summary.

before 'form_process_autocomplete', it should say '@param array $element' instead of '@param $element'

I was debating whether this was scope creep, but I agree it's a bad idea for the docblock to be inconsistent.

Attached patch corrects the issues identified in #6.

+++ b/core/includes/form.incundefined
@@ -2857,7 +2911,14 @@ function form_process_password_confirm($element) {
+ * @param array $element
+ *   An associative array containing the element structure, including its
+ *   properties and children.
+ * @param array $element_state
+ *   An associative array containing the current state of the form element.
+ *   Passed by reference.

@@ -2965,6 +3030,10 @@ function form_process_date($element) {
+ * @param array $element
+ *   An associative array containing the date element structure, including
+ *   its properties and children.

@@ -3532,6 +3634,13 @@ function form_process_machine_name($element, &$form_state) {
+ * @param array $element
+ *   An associative array containing the machine name element structure,
+ *   including its properties and children. Passed and updated by reference.
+ * @param array $form_state
+ *   An associative array of data for the current state of the form that
+ *   contains this element. Passed by reference.

@@ -3915,6 +4027,13 @@ function theme_email($variables) {
+ * @param array $element
+ *   An associative array containing the email element structure, including its
+ *   properties and children. Passed and updated by reference.
+ * @param array $form_state
+ *   An associative array of data for the current state of the form that
+ *   contains this element. Passed by reference.

@@ -3995,6 +4114,13 @@ function theme_range($variables) {
+ * @param array $element
+ *   An associative array containing the number element structure, including
+ *   its properties and children. Passed and updated by reference.
+ * @param array $form_state
+ *   An associative array of data for the current state of the form that
+ *   contains this element. Passed by reference.

@@ -4075,6 +4201,13 @@ function theme_search($variables) {
+ * @param array $element
+ *   An associative array containing the url element structure, including its
+ *   properties and children. Passed and updated by reference.
+ * @param array $form_state
+ *   An associative array of data for the current state of the form that
+ *   contains this element. Passed by reference.

So, there is a case to be made that those do not need to be documented, since the parameters are always the same:

• None of the element type validation handlers in form.inc have parameter documentation, and maybe it makes sense to be consistent with form element validation handlers generally for specific elements.
• Two are inconsistently named and documented, date_validate() and password_confirm_validate(). (The latter also has weird parameter names.)
• Some get the $element parameter by reference and others don't. @jhodgdon and I weren't sure about this (and I think @hosef is also referring to this above).
• The form process callbacks are similarly inconsistent. Some have currently have parameter documentation and others do not; the parameters are inconsistent; etc.

darn you dreditor

sun has filed: #1552308: Consistently make all form callbacks take $element by reference.

Though it looks like the range validation callback actually needs to be a value function.

I'll look for some more references on the documentation question.

Updated issue summary.