Clean up API docs for file module

This one was rather quick.

I had to get creative with the various Form/Render API callbacks, though. Generalizing from the new callback standards, I went with "#property callback: ..." for the introductory line (e.g. "#process callback: ...").

Attached patch straight-forwardly fixes (a), (d), and (e, I think I caught all of those. At least the ones that had the same misspelling).

For (b), I went with:

 * Form submission handler for upload and remove buttons of field_widget_form().

Seeing as it is not really a submit handler for the whole form, but rather for the file field specific stuff---which should be mentioned in the summary line. Relatedly, I was not sure what to do with (except fixing the embarrassing "hanlder" typo):

 * Form submission hanlder for upload / remove buttons of managed_file elements.

so I left it as is for now. The problem is that there is no single form constructor where these are used---rather, they are registered by the #process function for file_managed form element types.

Also, I left the #-callbacks untouched until we resolve what should be done:

I think that "Element validate callback:" is quite unclear. Even as someone who knows about the #element_validate property, it is not immediately clear to me what this means. By contrast "Access/Title/Page callback" is likely to be familiar to anyone who ever implemented hook_menu().

Two suggestions:
(i) Don't mention that this is a callback in the summary at all, but include a line later, saying "This is assigned as a #element_validate callback in foo_bar()".
(ii) Have a generic "Render API callback: ..." as the summary, and include a line as mentioned above.

I think (ii) is better. Generally, the hope is that once we figure out a way to automatically document the #-properties, things like '#element_validate' can be auto-linked.

Changed all the "#foo callback: ..." lines to "Render API callback: ..." and added a line to the docblock saying where this is assigned and to what property.

Only remaining caveat: I've changed all of those to "Render API callback: ..." though many of these would be considered Form API callbacks, if one makes such a distinction. There does seem to be a building consensus, however, that Form API really should be seen as subset of Render API (and, after all, all forms go through
drupal_render() at the end, so the form specific stuff that is done prior to that can be seen as preprocessing the elements for rendering).

However, if people disagree, I could change those to "Form API callback: ...".

Fixing these, but:

(b)

 + * Tests upload and remove buttons for multiple multi-valued File field.

The "multiple is in fact not redundant, as the test creates two multi-value fields and tests those:

$this->createFileField($field_name, $type_name, array('cardinality' => 3));
$this->createFileField($field_name2, $type_name, array('cardinality' => 3));

But, of course, that means that it should be "multiple multi-valued File fields" (not "field").

(c) With "and" and "does", this went over 80 characters ... but looking at the test, I actually don't see any additional, mimedetect-dependent tests. So I just changed this to "Tests file extension checking."

Hm ... I agree that "multiple multi-value fields" is not the finest prose, but "several" tends to get a "specific" reading in English ("There are several multi-value fields. This functions tests those."), which is not what is meant here.

I tried variants of "multiple file fields with multiple values", but could not fit those into 80 characters.

Oh, and:

Looks pretty good! I like how those element validate callbacks are documented -- seems very clear, and points people to where the items are being used/defined/added to arrays. Excellent!

Should we make this a standard? Between our (newish) standards for callbacks that get directly passed to functions, menu and form callbacks, and hook implementations, this would close a gap (and this way of documenting those is most likely to be forward compatible to whatever gets decided in #100680: [meta] Make API module generate Form API documentation.

Hm, I was thinking of making this a standard for the sake of consistency. If some (many) functions use the "Render API callback: ..." + separate specification format for #pre_render callbacks, this might well lead someone to think that "Pre-render callback: ..." must means something else.

I like the "Render API: ..." format a little better, as it is more explicit (and also specifies where the callback is assigned). At the same time, #pre_render (and #post_render, #theme, #theme_wrapper callbacks) are special, as they are invoked by drupal_render() itself---meaning (a) that these properties always work and (b) that there is no specialized function invoking them. So it might make sense to (optionally) document these with a more menu-callback-like pattern. In any case, I think that, ideally, these should get an @see drupal_render() (and an @see to the function assigning the callback, if it is not mentioned in the doc text).