We need a place to put documentation for core subsystem hooks, other than system.api.php

I thought about core/api/$subsystem.api.php - the problem with that though is we have a lot of stray one-off hooks that would likely still need a generic core.api.php - so not sure if it's going to be possible to keep that consistent.

core.api.php would make it a lot clearer which hooks are actually invoked via system module, vs. just dumped there, so would be a good improvement apart from the field issue and we can always refine that further.

I think that is a fine suggestion... not sure it's very definite, let's see... I just did a quick "find" command and these are the api.php files we have now:

1) In core/modules/system:

system.api.php (contains generic hooks, not a great idea)
entity.api.php
language.api.php
theme.api.php

2) Quite a few of the core/modules/* directories have a (that module).api.php file.

That's it...

And what I think we are saying we want to do is:
- core/modules/system/system.api.php would contain hooks that actually pertain to the system module (if there are any).
- core/modules/foo/foo.api.php - hooks pertaining to the foo module
- ???/core.api.php - hooks for sub-systems that have only one hook
- ???/bar.api.php - hooks for the Bar subsystem if there are several

In the past, we've put the sub-system api.php files into core/modules/system, but maybe it would be good to put them somewhere else? maybe in core/lib? or core/includes? or core/lib/Drupal/Core/Bar (for the particular subsystem)? It seems like putting the subsystem hooks in the System module directory is not all that sensible?

Thoughts?

Fixed tags.

This has been resolved. We now have core.api.php. If we want to move some hooks in there, we can file separate issues on a case-by-case basis.