Updated: Comment #1


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


#2067809: YamlDiscovery uses basename of directory instead of module name


lostkangaroo’s picture

#double post

lostkangaroo’s picture

Concerning 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.

jhodgdon’s picture

Yes, 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"?

neclimdul’s picture

I'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.

jhodgdon’s picture

If 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.

ifrik’s picture

Missing terms should certainly be added to the glossary, or edited where existing definitions are not useful.
See #2430401: Updating the online glossary

jhodgdon’s picture

This issue is not about the drupal.org online glossary. This is about the API documentation needing some terms defined.