Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Updated: Comment #1
Problem/Motivation
The Drupal 8 API docs (and previous versions, of course) have implicitly coined a number of Drupal-specific terms. Examples:
- provider - used in plugin discovery and YAML parsing to refer to a module, distribution profile, etc. that might define plugins or provide YAML files
- entity - hard to even define what it means, really, if you don't already know!
- node
- path
- route
- Dependency Injection Container or just "container"
- etc.
These terms are used without explanation in API documentation. And I think they are being used consistently... However, they are Drupal-specific or have specific meanings in Drupal that are not generally known to software developers.
This makes it difficult for experienced programmers who are new to Drupal to understand what is going on by reading class/function API documentation.
Proposed resolution
a) Make a list of these terms, with definitions.
b) Put it in a Topic/@defgroup, probably in system.api.php
This way at least we could point programmers new to Drupal to this page so that they could learn about this terminology.
Remaining tasks
a) Make the list of possibly unfamiliar terms. This should exclude terms that are used on php.net or that are standard Computer Science terms, unless they have a Drupal-specific meaning that is different from their standard meaning.
b) Write definitions for these terms.
c) Create a @defgroup topic containing the terms and definitions. They should be listed alphabetically using our standard list formatting, like:
* - provider: A module, theme, or distribution profile, which may provide
* YAML files, plugins, services, other classes, etc.
(Note: I'm not saying this is the definition we should use, necessarily, just that it's the format we should use.)
User interface changes
We'll have a central place on api.drupal.org to point new developers to when they get confused about terminology. No affect on the Drupal UI however.
API changes
None.
Related Issues
#2067809: YamlDiscovery uses basename of directory instead of module name
Comments
Comment #1
lostkangaroo commented#double post
Comment #2
lostkangaroo commentedConcerning Resolutions
a) It looks like most Drupalism terms are listed at https://drupal.org/glossary thankfully reducing the amount of discovery needed for this, and should narrow our focus to terms introduced by D8.
b) I support this but worry about the maintenance cost in term addition and editing vs the already existing glossary page.
Comment #3
jhodgdonYes, that is a good point. Maybe we just need to make sure the new D8 terms are added to the glossary, and this issue can be about collecting the new terms and making sure they are there? Like "provider" for instance, and "container"?
Comment #4
neclimdulI'm not sure I'd document "providers" there are lots of providers like route providers, authentication providers, etc.
Really a "provider" in the plugin discovery systems is an internal structure and the fact that it shows up at all to users(through the definition) is a leak that probably shouldn't happen because the entire point of plugins is to interact with the class directly. I'll try to follow up with that.
Comment #5
jhodgdonIf that is the case then we should not be documenting parameters/vars in API docs as saying "A provider" but rather "A foo provider". But I will put this comment back on the other issue.
Comment #6
ifrikMissing terms should certainly be added to the glossary, or edited where existing definitions are not useful.
See #2430401: Updating the online glossary
Comment #7
jhodgdonThis issue is not about the drupal.org online glossary. This is about the API documentation needing some terms defined.
Comment #18
catchMoving to a task since this is really proposing a new documentation section, although I'm not sure that the API documentation is the best place for the general glossary (unless we also remove the page on Drupal.org?).
Comment #20
amber himes matzWe discussed this in a core documentation group triage Slack meeting (https://drupal.slack.com/archives/C220WV2TW/p1663030400116659) and based on catch's comment in #18 and the consensus reached in our discussion, we think that 1 glossary that covers all Drupal versions, and exists as a documentation page, not in API documentation is the way to go.
Closing this as won't fix in favor of #2430401: Updating the online glossary.