The 2026 Drupal Business Survey is open. Your response will help shape the future of the Drupal business ecosystem.This issue needs to be fleshed out...
I noted today that probably the Entity API topic, which is currently in core/modules/system/core.api.php, should probably be in core/modules/system/entity.api.php instead. Generically:
- Topics specific to a particular module should be in core/modules/modulename/modulename.api.php
- Topics generic to core should be in core/modules/system/core.api.php, or a subsystem *.api.php file in the same directory (such as entity.api.php).
- Sometimes, another location makes sense. For instance, there are Views topics for each plugin type, and these are located in the base class file, so that is probably OK. And for the topics that are mostly to list some functions in an include file, having them in that include file is also probably OK.
I am sure that if we go through the list of topics on api.drupal.org for Drupal 8, that there are other topics that should be moved as well. There are also a number of them that have misleading names or bad/missing one-line descriptions.
There may also still be some that are obsolete and should be removed.
So... This issue should:
a) Survey the topics and see if any should be moved, removed renamed, or have their descriptions updated.
b) Make a patch.
(For the Entity API topic, it would be good to wait until #2216535: Replace Node overview topic and Node API topic with Entity Hooks topic is taken care of.)
Comments
Comment #1
jhodgdonList of Topics needing attention:
- Annotation - should be in core.api.php not system.api.php
- Callbacks - should be in core.api.php not module.inc
- context definition plugin metadata - I think the documentation should be moved to the Annotation topic. Or else they should be linked together with @see. If we keep the topic, the title should be capitalized and it needs a one-line description. Actually, it would be good if the title started with "Annotations:" so it would appear next to Annotations in the topics list.
- Translatable plugin metadata - same as "context definition plugin metadata"
- Entity API - should be in entiy.api.php not core.api.php
- File module public API functions - should be removed. The one function listed in this topic can just be added to the generic File interface topic.
- Form generation - move to core.api.php. The many functions in form.inc that are listed on that topic page are not really relevant to form generation, so removing it from that file will not cause adverse consequences... maybe look through the list and see if there are a few relevant functions that need @ingroup form_api if they are really meant to be called by developers creating forms or doing things with them programmatically. The classes mentioned in the text should be given @ingroup form_api so that the appear instead.
- Hooks - move to core.api.php
- HTTP handling - remove. The one function that is in there could be given @ingroup form_api instead, as it is related to forms.
- Internationalization - move to core/modules/system/language.api.php
- Menu tree parameters - remove
- Queue operations - move to core.api.php and add relevant classes to the topic using @ingroup
- Theme system and render api - move to core/modules/system/theme.api.php
- Update manager module * - we do not I think need these topics?
- Update versions of API functions - not sure if we need this or not?
Also... Most of the hooks in core/modules/system/system.api.php are not related to the system module, but Core functions. They should be moved to core.api.php.
The next step is to file issues for these.. could be done in a few groups but I think one big issue would be too big. I'll see what I can do about making a logical grouping.
Comment #2
jhodgdonTurning this into a meta issue, and I'll file child issues.
Comment #3
jhodgdonIt looks like all the child issues for this got fixed; the hooks are a separate meta, so I'll go ahead and mark this one as fixed.