Contrib.social

Find a consistent way to document plugin types

Open on Drupal.org →
Created on 11 September 2013, over 11 years ago
Updated 12 March 2025, 28 days ago

Problem

In Drupal 7 plugins were defined through hooks and hooks (of any type) were documented in *.api.php files. Period. Any developer wanting to know about the possibilities to extend a module would only have to look in that module's *.api.php file.

In Drupal 8 we have a few new ways to define plugins, such as annotated classes and YAML discovery. We need a consistent way to document these within the module files, so developers know where to find the documentation and won't have to go looking online for it, because a lot of them won't have a connection when coding when travelling or because it's not as widespread in some parts of the world as it is in others.

One suggested way to documented annotated classes is on the base class (see #1912658: Document views access plugins → for an example), but plugins may or may not be able to use them or implement interfaces. It is not so much the exact contents of the documentation as well as the centralized location and format of it that I am concerned about. Our hook documentation is pretty solid and with a couple times more plugin types in D8 than in D7 we do not want to cause a regression by providing a lesser documentation experience (DoX?).

Proposal

In every module, create a /documentation/plugins subfolder with one file per plugin type.

📌 Task
Status

Postponed: needs info

Version

11.0 🔥

Component

plugin system

Created by

🇬🇧United Kingdom Xano Southampton

Live updates comments and jobs are added and updated live.
  • stale-issue-cleanup

    To track issues in the developing policy for closing stale issues, [Policy, no patch] closing older issues

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • Comment 28 days ago →
    🇺🇸United States smustgrave

    Thank you for creating this issue to improve Drupal.

    We are working to decide if this task is still relevant to a currently supported version of Drupal. There hasn't been any discussion here for over 8 years which suggests that this has either been implemented or is no longer relevant. Your thoughts on this will allow a decision to be made.

    Since we need more information to move forward with this issue, the status is now Postponed (maintainer needs more info). If we don't receive additional information to help with the issue, it may be closed after three months.

    Thanks!

  • Comment 28 days ago →
    🇬🇧United Kingdom joachim

    This is absolutely still relevant. There is no proper documentation on plugin types the way that there is for hooks.

    Nobody has worked on it because it's a big undertaking.

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024