Inadequate documentation of return value and parameter for hook_form()

No, http://api.drupal.org/api/drupal/includes!form.inc/group/form_api/7 is not enough. While that is useful, it's not remotely adequate. That document doesn't describe the data structures.

In technical documentation hypertext, the precise structure and meaning of any data element (parameter, return value, etc.) should be either on the same page or available in a single click.

Here's some perspective:

As someone just getting into Drupal development, this hook_form() page is completely baffling to me. What is $node? An object? An array? A machine name? A node ID number? An identifier for the node type? I have no idea, and this page gives me no hint on how to find out. The same is true for the return value and form_state structures.

I shouldn't have to muck through a series of long documents to find out.

I should be able to click on a link right there next to or on the item (parameter or whatever). That link should take me to a document that describes only whatever it is I clicked on, or to the proper section of a larger document.

Thanks for the tips, but that's not the point. A reference for a function should give all information required to use that function, or link to that information. Having a link to the form API is an excellent idea (and should be done), but not enough.

Have a look at http://www.php.net/manual/en/simplexmlelement.addchild.php.

The function (well, method) is completely prototyped. You can see instantly what the types are for the return value and parameters. The return type (SimpleXMLElement) is a link, so you can look up that type. The left column is a breadcrumb, so you can click to look up information about the SimpleXML system or XML manipulation in general. There's a link to a basic usage guide, so new users can get started there. It's clean and fast and gives the reader almost everything.

Or, consider a Linux man page: http://www.kernel.org/doc/man-pages/online/pages/man2/stat.2.html . It includes a fully commented data structure used by the functions documented there. Even though the people using that manual already have a lot of background knowledge, it's still fully documented. That data structure isn't hiding in some obscure document about file system inodes that isn't even mentioned in the function documentation. It's documented right there with the function, because people writing code with that function need to know about that structure.

Here's what I'm talking about. Instead of THIS:

Parameters

$node: The node being added or edited.

$form_state: The form state array.

Return value

An array containing the title and any custom form elements to be displayed in the node editing form.

It should be more like THIS:

Parameters

string $node: The node ID number or node type machine name of the node being added or edited.

array &$form_state: The form state array. See form_state for the array structure. Modify the contents of this array to set the initial state of the fields in the form. The hook implementation can modify the state of any pre-existing field or of any fields it adds.

Return value

An array containing the title and any custom form elements to be displayed in the node editing form. See form array for the array structure.

See how much easier that makes it to get the information? Readers can just click on the links to get information about the structure.

Then there's the example. It's confusing. The example heading is labeled "Code". It should be labeled "Example" or "Example Code", because it's an example. The function name in the example shouldn't be "hook_form". It should be "example_form" and have the comment about "* Implements hook_form()".

Instead, we should be providing a link to the main Form API page, and if that page doesn't have information that it should, we should patch it so it does.

Yes, that works. One click to the necessary information is fine, so long as it's obvious where to click. If the format is used by multiple functions, it's good to have it documented in one central place. That way, if the documentation needs to be updated, you only have to update it in one place.

Looking around the Form API docs I could find:

http://drupal.org/node/37775 (Form API top-level doc): Doesn't provide any information about the data structure.

http://drupal.org/node/1702548 (Form API Overview. Create forms with hook_form (Drupal 7.x)): Good partial information. Should be linked from the function doc page and perhaps be enhanced.

http://api.drupal.org/api/drupal/developer!topics!forms_api_reference.ht... (Form API Reference): Excellent detailed documentation of each element, but no high-level description of the array. Add a couple lines to document the array, and then every page that documents a function that uses the array can link to it.

I was not able to find any documentation of &$form_state anywhere.

The hook_form() doc mentions hook_form($node, &$form_state). The Form API Overview mentions mymodule_formname($form, &$form_state). I still couldn't find any documentation on what the $node/$form parameter does or what data type it is, although the hook_form() example gives a hint. Also, I think it should be mymodule_form(), or the hook system won't work, right?

Anyway, please provide a patch with your suggested changes to the hook_form() documentation and we'll get it reviewed and committed. Thanks!

I'll give it a shot, so long as everyone understands that I'm not that familiar with the material and might get it wrong (that's why I was reading the documentation). Also, given that I'm new, I've no idea how to make or submit a doc patch. Mind pointing me to directions on how to do that?

I found good documentation of $form_state at http://api.drupal.org/api/drupal/core!includes!form.inc/function/drupal_.... Maybe it could be moved out to it's own doc and replaced with a link.

The good documentation at http://api.drupal.org/api/drupal/developer!topics!forms_api_reference.ht... just needs a little bit more info to describe the high-level structure, then any doc for a function that uses the form array can link to it.

I still don't know the remaining details of the return value array nor the $node parameter. (This is the original problem.) Also, I haven't found any instructions on the proper way to update documentation (It's a patch??). So, I can't write the doc patch. Is anyone reading this who can point me to the required information or can make the patch?