UNSTABLE-4 blocker: Add api.php for every core module

I like the idea of moving stuff in http://cvs.drupal.org/viewvc.py/drupal/contributions/docs/developer/ to core. Having documentation available in core is very handy, and definitely would help when visiting api.drupal.org is not an option.

The thing I like about it is that we can ensure that the documentation for hooks gets reviewed and committed and at the same as the code changes.

Wait... actually combining the two would have one big downside. The code required to check that a hook's been called for unittesting is totally not the sort of code that you'd want to show up as an example of implementing the hook.

This patch takes the hook documentation found here and sticks it in a hidden module. Not too sure where to go with the test system though. Visiting admin/build/modules doesn't display the Hook module.

A certain amount of contrib modules is also implementing hooks. Instead of a hidden module in core, I'd rather like to see a unified way for including developer documentation compatible to API module. What about creating a sub-folder /hooks in each module (system for other core hooks) that contains one or multiple files?

http://drupal.org/node/224333#remove_op

Let me preface this comment by saying +10,000 for having hook documentation in core. Moving the database schema documentation into core was one of the best things we ever did and has greatly helped to ensure that fields are a) documented at all, b) continue to be updated throughout the ages.

However, I don't like this exact approach.

a) While catch's #5 is a good point, I would prefer to find a solution that could work equally well for both core and contrib. Each module defining its own modulename.hooks.php file, or similar? Basically, see sun's #6.

b) However, the question then comes up of how to deal with hooks exposed by core include files (menu, file, etc.)? Blah.

c) I'm a little leery of using module.hook.inc, because module.*.inc is generally used for page-splitting patches and people might get confused that that's where you need to put your "implementation of X" in there. I'd prefer a clearly different naming convention altogether.

d) I prefer precision tests, such as the file and db tests, over a gigantic hook.test trying to test every nuance of every hook. Maybe I misunderstood that point.

What about having each module ship with an api.php in its directory. Its only purpose is for api.module to scan it. That's more modular than a single hooks module and applies equally well for contrib.

I like that idea. But will API module choke on multiple files named the same thing?

I guess if it will, we could always just fix API module. ;)

Ok. Let's do it!

api.php in each module directory. Misc. crap in the includes directory gets put into modules/system/api.php.

GO! :)

In some contrib modules (like Views), there are multiple modules that live in the same directory. Does this mean that the api.php would include the API for all the modules in that directory? If we used modulename.api.php, then the hooks for each module in that directory could be defined all in separate files.

Will SimpleTest call these hooks during tests?

IIRC you can't have multiple modules in same directory after the registry patch. I might be remembering wrong. i'm fine with modulename.api.php (or .inc?) if needed

That Views question is interesting. Especially when you consider something like Ubercart with 50,000 sub-modules or so.

I'm starting to now lean in the other direction: A single 'hooks.php' in the root of the 'project' with /** @defgroups **/ as makes sense, with ALL of the hooks defined by that project, regardless of where they live. That's better from a DX perspective as I don't need to go traipsing through directories to get a big picture of what a thing does. It also makes this patch much easier to roll. :)

So in core, we could have @defgroup Core, Node, etc.

Views might have @defgroup View styles, View plugins, View yo momma

Does that make sense?

Surely modulename.api.php is more consistent with modulename.module, modulename.info, modulename.install

Sure, I'm not too fussed about the name (other than it should not be .inc, because it's never being included anywhere). I'm more interested in whether the approach is sound.

if I were developing many sub-modules, I'd want the ?.api.php file to be grouped with each module - anything else would seem like a nightmare to track and fix.

Yes, one api.module in each module subdirectory. If you aren't dividing your modules into subdirectories in a project, you are not following best practices and we need not specify an api.php convention for this.

I am right now in the situation of having to document Wysiwyg API. My considerations and reasoning:

First, I placed a file api.php in the module folder.
That looked at bit lost, because all other files in the folder are prefixed with the name of a module.
Renamed to wysiwyg.api.php.
Makes more sense and is more consistent now.

Also, I can see modules like Views or eCommerce that provide so many API hooks that a single file would be cumbersome.
Sure, the best practice is to have sub-modules in sub-folders.
But then again, look at Views and Views UI, both being in the module's root folder. Both may or may not provide API hooks.
Usually, core avoids too strict rules where they are not required.
If we simply define a standard like module.api.php, systems like API module or SimpleTest can search for a certain filename pattern, regardless of the file's location.
So if we would want to place all core API documentation in one folder, we could do so; i.e. node.api.php, user.api.php, etc.
The same for contrib modules.
However, we could also place node.api.php in modules/node/ - what matters is just the filename.

Hence, +1 for <module>.api.php

In the end I think that drumm should have the final word on this.

i'm in agreement with sun's reasoning in #24.

Where will the core hooks go that are not associated with a module? In modules/system/system.api.php? includes/api.php?

I went through the hook documentation and attempted to move all the hooks to their designated module.api.php. I also placed a includes/api.php for hooks that are not quite associated to any module. Some of api.php might belong in system.api.php, however.

As discussed on IRC with webchick, tha_sun and add1sun, we decided to move all of includes/api.php to modules/system/system.api.php.

Forgot the patch....

Some of the descriptions were incorrect....

We can simplify this to "Hooks provided by Xyz module.":

+/**
+ * @file
+ * These are the hooks that are invoked by the Locale module.
+ */

Probably all of those are not required and can be removed:

+/**
+ * @} End of "addtogroup hooks".
+ */

hook_hook_info() in system.api.php belongs into trigger.api.php, I guess.
hook_update_index() in system.api.php belongs into search.api.php, I guess.

There are 2 @file definitions in node.api.php.

EDIT: Oh, and did I say: AWESOME! ? ;)

I'd like to get this in in UNSTABLE-4. It's starting to get annoying tracking all the various follow-up issues and request for documentation after the fact for new/modified hooks.

also nodeapi is now out of date

sorry for title change

Updated this a bit:

• Updated to grab the latest changes to the docs: addition of hook_js_alter() and hook_taxonomy broken out by op, and REQUEST_TIME.
• Moved hook_update_index() to search.api.php.
• Moved hook_hook_info() to trigger.api.php because it sure looks like trigger is the primary consumer of that info and all the actions hooks are in there.
• "These are the hooks that are invoked by the Xyz module." -> "Hooks provided by Xyz module."

Didn't mess with the hook_nodeapi docs at this point.

+/**
+ * @file
+ * These hooks are defined by node modules, modules that define a new kind
+ * of node.
+ *
+ * If you don't need to make a new node type but rather extend the existing
+ * ones, you should instead investigate using hook_nodeapi().
+ *
+ * Node hooks are typically called by node.module using node_invoke().
+ */
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
+

that extra hunk should be taken out... was a remnant of when node hooks were in hooks/node.php instead.

here's a re-roll without the wierd @file chunk in the middle of node.api.php.

Thanks a lot, Drewish. Looks great! RTBC * 2.

Awesome. Apart from some desperately needed clean-up we have left in some of this documentation, this looks really great, and will ensure that all future hook changes and additions aren't committed until they update the API documentation. It will also help people frequently on planes who don't keep a checkout of contributions/docs/developer/hooks with them.

Committed to HEAD. Thanks! :D

We need some upgrade documentation, please.

I don't understand why there are changes to system.test and system.module in this patch that was committed... It is related to temporary file cleanup and not related to apis at all.

That was my bad... I'd accidentally rolled #330633: Temporary file cleanup needs some love (UnitTest included!) in.

Here's a reversal of http://cdn1.drupal.org/files/issues/file_330633_2.patch which should do the trick.

Yup! Dave Reid has ninja eyes that are better then both webchick's crazy eagle eyes and my lack-of-coffee eyes.

Bumped to critical: the code that sneaked in broke PostgreSQL installation with message:

PDOException: SELECT fid FROM {files} WHERE status & :permanent != :permanent AND timestamp < :timestamp - Array ( [:permanent] => 1 [:timestamp] => 1227604875 ) SQLSTATE[42P18]: Indeterminate datatype: 7 ERROR: could not determine data type of parameter $2 in system_cron() (line 1511 of /var/www/drupal/revamp/modules/system/system.module).

Committed to CVS HEAD. Thanks.

Added update documentation.

Should we delete all the files in the contributions/docs/developer/hooks/ now?

I think it'd be a good idea since api.drupal.org is using the new .api.php files: http://api.drupal.org/api/group/node_access/7

I removed all the files from the directory. If we notice missing documentation once api.drupal.org regenerates, we'll have to file separate issue to put it in our new core api.php files!