Contrib.social

[Meta] Document format/content of various YML files

Open on Drupal.org →
Created on 19 August 2014, about 11 years ago
Updated 5 September 2025, about 2 months ago

Problem/Motivation

#1996238: Replace hook_library_info() by *.libraries.yml file → introduced *.libraries.yml, but didn't document the format. There are also some other *.yml files with no documentation on api.drupal.org

Proposed resolution

Generally, the idea for API documentation in Drupal Core is:
- Make sure there is a topic (@defgroup in a core api.php file) that gives you the bare minimum documentation for that API -- not necessarily all the details, but at least the basic syntax/usage/etc.
- Make sure the topic is linked from the landing page on api.drupal.org for Drupal 8, or that there is a logical path to go through to find it (e.g., if you were documenting the API for making menu links, it should either be in a topic with "menu" in the name that is listed on the api.d.o landing page, or if you go to the "menu something" topic that is listed there, that page should link to this other topic that has this information in it).
- From the "bare minimum" @defgroup topic, link to more detailed documentation on d.o. The page on d.o should give you more details, in more of a tutorial style.

Remaining tasks

The *.yml files in Core are listed in comment # 26. Most of them are documented OK, but there are 4 child issues that need to be resolved. Each one is rounding out or adding documentation for one of these *.yml files.

User interface changes

None.

API changes

None.

📌 Task
Status

Postponed: needs info

Version

11.0 🔥

Component

documentation

Created by

🇧🇪Belgium wim leers Ghent 🇧🇪🇪🇺

Live updates comments and jobs are added and updated live.
  • Documentation

    Primarily changes documentation, not code. For Drupal core issues, select the Documentation component instead of using this tag. In general, component selection is preferred over tag selection.

  • CSS

    It involves the content or handling of Cascading Style Sheets.

  • Coding standards

    It involves compliance with, or the content of coding standards. Requires broad community agreement.

  • 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 about 2 months 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 about 2 months ago →
    🇬🇧United Kingdom joachim

    Yes, OBVIOUSLY. None of this has been done.

  • Comment about 2 months ago →
    🇳🇿New Zealand quietone

    @joachim, I don't there is a need to shout at anyone here.

    To say none of this is done seems incorrect as the 4 child issue are complete. And even the remaining task section here does implies that this is waiting on the child issues to be completed.

    In #45 you said that the new issue made there would cover this issue. Does that mean to continue the work over there or something else?

  • Comment about 2 months ago →
    🇬🇧United Kingdom joachim

    @quietone I am getting really frustrated with issues that are patently still relevant getting this stale issue copy-paste comment posted on them.

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024