hook API documentation files have no information about where hooks are to go

Good point!

So the patch needs work, because definitely if you want those hooks to appear in a particular group page on api.drupal.org, you need to do a defgroup as well as ingroup.

I would also be in favor of adding a line to each of those hook docs, like:

Note that implementations of this hook belong in your module's mymodule.install file, rather than the mymodule.module file.

The problem is that if you add a tag like @ingroup abcdef, it will not be displayed on api.drupal.org at all if there is no corresponding defgroup.

Which is why I think it is best to just put some explicit text in there saying that the hook implementation belongs in file xyz.ext, rather than being cryptic by using a tag that not everyone will understand necessarily.

Where's the patch?

There's some bad formatting in your patch:

+                                                                                                     /**
+ * Check installation requirements and do status reporting.
+ *
+ * This hook has two closely related uses, determined by the $phase argument:

I also think the name of your defgroup could be simpler... how about just install_file_hooks?

Also, to make the patch less scary, how about just defining the defgroup, leaving the hooks grouped as they currently are, and adding the @ingroup to the individual hooks (as you had it before), rather than moving them so they are all together? It seems like that would make it more certain that anyone reading the raw doc would notice that the hooks are in that group, because that file is pretty big, and they might very well not notice that @defgroup if they're looking at a particular hook doc.

Finally, have you tested your patch with the API module to verify that it correctly makes this group, and adds all the hooks to that group as well as leaving them in the plain Hooks group? Whoever marks this RTBC needs to do that (just noting this mostly as a reminder for myself).

And by the way, once the defgroup name is standardized, I think we can easily do this for D6 as well. Especially if it's a relatively simple patch (just adding @ingroup to a bunch of hooks, and a @defgroup to one of the hook files). But we should agree on the format in D7 first and get it committed there before fixing D6 (in the contrib repository), so that we do it exactly the same in D6 and things will link correctly on api.drupal.org.

I still don't like the name, but I suppose module_builder probably wants to be general (such as Views hooks, etc. that also might need to go in different files)? So I'd be willing to live with the complicated name.

I still think it would be better to use @ingroup than to move all the hooks around in the file, though, and the formatting still needs fixing. And the patch needs to be tested with the API module, either by you or by the patch reviewer/me, to make sure it actually works (creates the topic group with the installation hooks in it).

Not critical. Please read and understand Priority levels of Issues, thanks.

I am downgrading this issue from critical to normal.

Not having the location of hooks documented on api.drupal.org will not block the release of Drupal 7.

There are two reasons:
a) Most module developers already know where hooks go.
b) It is documented in module building guides etc. in the Handbook.

I am not saying we should not fix it, but it truly is not a release blocker. I realize you feel strongly about it, but apparently you have higher priorities than supplying an acceptable patch, as do we all -- this is just not as critical as many of the issues that are of status "normal" in the Drupal issue queue.

#9: 633332-2.drupal.system.add-install-location.patch queued for re-testing.

There is an issue here about where hooks NEED to go vs. where they SHOULD go---e.g., in D7 hook_install()-implementations work perfectly fine if placed in .module files (as those are loaded on install), but they SHOULD go in .install files, AFAIK. The only things that NEED to go into .install files is functions that need to be present on uninstall (such as hook_schema and hook_uninstall implementations).

Not sure where hook_module_enabled() implementations should go --- .module files seems sensible to me.

hook_modules_* have to go in the module files, because these are ways for modules to respond to other modules being installed/enabled/etc.

The only ones that should go in the install file I think are:
hook_install
hook_uninstall
hook_enable
hook_disable
hook_schema
(and I am doing this from memory so I may have some of the names wrong -- did I miss any?)

Anyway, because of #1247626: hook_install/hook_uninstall doc does not specify that the implementations must live in the .install file some of these are now appropriately documented...

Can someone who is interested in this check the 8.x API site please, and see which hooks still need a note that they belong elsewhere besides in the .module file (whether they *should* or *must* be, I think we could add notes to the doc)? Because most hooks belong in the .module file, I think we should only document the exceptions, right?

A quick rundown ("Yes" means the hook doc says where the implementation must/should go):

• hook_install(): Yes.
• hook_uninstall(): Yes.
• hook_enable(): No, needs a "should" comment.
• hook_disable(): No, though implicit in "Perform necessary actions before module is disabled."---"should" comment needed.
• hook_schema(): Yes.
• hook_schema_alter(): No, needs a "should" comment (at least I THINK this is not called on uninstall, and hence could live in .module).

There is, of course, still the issue of finding a parseable way to indicate that a hook should go into the install file. I rather like the idea of introducing a new file to contain .install hooks. I'd prefer MODULE_NAME.install.api.php.

(True, few modules besides system will have this file, but a general convention is useful.)

There also is hook_field_schema(), which does already have a note about having to be in the install file.

I opened #1309298: Document that hook_(en|dis)able implementations should live in .install files (with a patch attached) in order to add the missing info to the documentation of hook_enable() and hook_disable().

I did this in a new issue so that we can keep discussing here how this info could be provided in machine-parseable format.

I also opened #1309302: Improve hook_schema_alter() documentation., but sans patch for now, as I am not sure what the actual behavior is.

I really think that if we want to add this information in a machine-parseable form, we have two options:

(a) Introduce a new file name scheme as suggested in #21.
(b) Introduce a new doxygen directive specifically for this purpose, as @ingroup will not work with proper file names / file name patterns.

(a) would be more conservative, in a way, while (b) would be more general.

Do you have a suggestion of what this directive would look like?

Also... aside from the few remaining hooks in 8 that go into the .install file, there is hook_hook_info() that can be parsed to see what hooks go into special include files:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Extension!module....

So it seems like module builder could parse those implementations, and have a very short list of hooks that belong in the .install file. Right?

Maybe... My feeling is that documentation that has to be maintained separate from code is unlikely to be maintained. We have hook_hook_info(), which is code, which determines where hooks should be. I don't think we should also enforce a documentation standard that provides the same information. Having the same information in two places is just asking for it to be inconsistent.

For the hooks that should be in the .install file... they are few... and if they are in a .module file, it is not a major problem (I think they will still work, it's just a bit less efficient).

Is this a bug or a task? Yes documentation has bugs, but is added this missing info a bug?

Optimistically changing the category.