Make sure all hooks in D7 have documentation

OK, here's a list of the hooks that have documentation (I grepped in *.api.php files for "function hook_").

And here's a diff file between the two.

Anything with a < means I think it's a hook and I think it is NOT currently documented.

Anything with a > means it is currently documented but I am not sure if it's really a hook (but it probably just means I missed it).

Gosh, that's a big list to go through and see what's really happening!!!!!!!!!

Sigh.

NOTE: I am making an annotated list of what needs to be done from the differences file - checking through all of them... will report back shortly...

There were a few left-over files in my area (old versions, etc.), so a few of the hooks were bogus... Also, I apparently missed boostrap_invoke() and _field_invoke_*() functions as more ways to invoke hooks. And there are of course a few places where someone didn't use module_invokes() or any of those other things at all, sigh.

OK. Phew.

There are about 30 hooks that need documentation.

See attached file for the list, along with notes of where they are invoked. A few separate issues have been filed, as noted. Otherwise, they are open for patches...

Now that there's a list of hooks that need doc, I guess it's a critical issue. Probably even a critical meta-issue.

I suggest that anyone who wants to help with this issue
a) File a separate issue with a title something like "hook_abc is not documented", with component "documentation", project Drupal, category "bug report", priority "normal" (so as not to clutter up the critical issue queue). You could put a couple of related hooks into the same issue if you want.
b) Comment here, with a link to the issue, explaining which hooks you have taken charge of.
c) This file has all kinds of helpful information on where the hooks are called, etc.: http://drupal.org/files/issues/tofix.txt

Here are the hooks that need doc. As people file issues, I'll update this list with links to the issues.

UPDATE - As of April 23, 2010, all of the issues here at least have patches, except the extra issue at the bottom about hooks that lack function bodies in the Field API! Most patches have been reviewed even; a few still need review. YIPPEE!!!!

hook_ajax_render_alter - FIXED - #713794: hook_ajax_render_alter() is undocumented
hook_archiver_info_alter - FIXED - #708574: hook_archiver_info_alter() is not documented
hook_batch_alter - FIXED - #717602: hook_batch_alter() is undocumented
hook_countries_alter - FIXED - #717666: hook_countries_alter() is undocumented
hook_cron_queue_info_alter - FIXED - #718648: hook_cron_queue_info_alter() is not documented
hook_date_format_types_alter - FIXED - #718894: hook_date_format_types_alter() is not documented
hook_field_attach_purge - FIXED - #776694: hook_field_attach_purge is not documented
hook_field_extra_fields_alter - FIXED - #719432: hook_field_extra_fields_alter() is undcoumented
hook_field_languages - Went away - see #776982: hook_field_languages() is not documented
hook_field_purge_field - FIXED - #777092: Field purge hooks are not documented
hook_field_purge_instance - FIXED - #777092: Field purge hooks are not documented
hook_field_storage_purge - FIXED - #777098: Field storage purge hooks are not documented
hook_field_storage_purge_field - FIXED - #777098: Field storage purge hooks are not documented
hook_field_storage_purge_instance - FIXED - #777098: Field storage purge hooks are not documented
hook_field_storage_update_field - FIXED - #777100: hook_field_storage_update_field is not documented
hook_field_ui_view_modes_tabs - FIXED - #777102: hook_field_ui_view_modes_tabs() is undocumented
hook_field_update_forbid - FIXED - #775936: hook_field_update_forbid() is undocumented
hook_filetransfer_backends - FIXED - #727282: hook_filetransfer_backends() is undocumented
hook_hook_info_alter - FIXED - #777080: hook_hook_info_alter() is not documented
hook_language_init - Someone fixed this one.
hook_language_switch_links_alter - FIXED - #675144: doc header problem in translation_language_switch_links_alter()
hook_process - FIXED - #736326: hook_process() and associated hooks are undocumented
hook_preprocess - FIXED - #736326: hook_process() and associated hooks are undocumented
hook_rdf_namespaces - FIXED - #623684: Improve documentation of rdf module
hook_search_page - FIXED - #171317: hook_search_page not appearing on api.drupal.org
hook_themes_disabled - FIXED - #491214: implement the top level Appearance / Choose Theme admin page
hook_themes_enabled - FIXED - #491214: implement the top level Appearance / Choose Theme admin page
hook_token_info_alter - FIXED - #673462: Complete API documentation for hook_tokens(), hook_token_info(), hook_token_info_alter() needed
hook_trigger_info_alter - FIXED - #776728: hook_trigger_info_alter() is undocumented
hook_updater_info - FIXED - #605270: Document new update manager hooks
hook_updater_info_alter - FIXED - #605270: Document new update manager hooks
hook_verify_update_archive - FIXED - #605270: Document new update manager hooks

See also: #675116: field.api.php hook documentation is incomplete - for several hooks that have doc headers but no function bodies.

You're welcome!

Two of the above issues have been patched/committed... So there are now "only" 24 hooks above without issues filed, plus 3 filed issues.

12 of the Completely Undocumented are field hooks. Probably someone who knows about the field API should take care of those, as well as #675116: field.api.php hook documentation is incomplete.

7 of the Undocumented are _alter hooks, where the non_alter hook has been documented, so they should be easy.

The other 5 need someone to research what their inputs/outputs are and write the doc. Hopefully the notes in http://drupal.org/files/issues/tofix.txt will at least provide the starting point for research, and hopefully at least one module in core currently implements them so there will be an example.

Anyone who wants to help on this is most welcome! :)

Those working on API doc issues should see this already, because it's in the documentation component. :) I thought Needs Doc was usually for things needing to go into the module/theme upgrade guides?

bump!

So all of the hooks at least have issues now (see #5 above). There are still a few that need work or initial patches, but we're getting there -- special thanks to robeano and heyrocker!

Status:
Everything has now been patched, except
#675116: field.api.php hook documentation is incomplete

That issue still needs a considerable amount of work, filling in function bodies for field API hooks.

Status update:

OPEN: #675116: field.api.php hook documentation is incomplete
There are still several hooks in there that are missing function bodies. It has been proposed as a Google Code-In project (see that issue for details).

NEEDS WORK: #929208: Path hook api docs are missing function bodies
This issue was reported recently, and has a patch that just needs a little tweaking

Removing redundant tag. Only #675116: field.api.php hook documentation is incomplete is still open on this issue.

Since we're down to just one issue now, I think it's time to close this issue.