Problem/Motivation
Not sure exactly which issue queue this should live in - seems like a core decision whether we want to do it or not, but to make it work, we'd need to figure out how things show up on Drupal.org which will need the DA. Putting it here for now but we can add spin-off issues as necessary.
High level Drupal API docs live in two places at the moment:
1. In core.api.php in phpdoc syntax
This generates pages like https://api.drupal.org/api/drupal/core%21core.api.php/group/cache/11.x
2. In the Drupal.org handbook.
https://www.drupal.org/docs/8/api/cache-api/cache-api
--
core.api.php can obviously be updated via a core MR, but despite being both a core committer and cache API maintainer, trying to do anything but the most basic changes here fills me with dread - I really dislike using phpdoc for prose.
The Drupal handbook can be updated by anyone with permissions, but it's never clear to me how or when to make a big structural update to pages. For example the first page of https://www.drupal.org/docs/8/api/cache-api/cache-api immediately jumps into mentioning quite complex caching concepts with no preface, and mixes the low level cache API and render caching together without clearly delineating between the two. But if I wanted to embark on a full rewrite of that page, can I just do that or does it need a documentation issue first?
On the other hand, if I want to look at Symfony cache component documentation, I can go here:
https://symfony.com/doc/current/components/cache.html
Or for Laravel: https://laravel.com/docs/11.x/cache
Symfony's docs are stored in a dedicated repository in .rst syntax, which is similar to markdown.
Steps to reproduce
Proposed resolution
I don't know what the end point of this is, but I feel like we should not be storing and editing long-form prose in PHP comments detached from actual code (i.e. what we do in core.api.php).
Options
1. Take high level conceptual documentation out of core.api.php into the handbook - e.g. rewrite the handbook cache documentation and open an issue to remove that section from core.api.php or replace it with a link.
2. Find another way to provide version controlled high-level API documentation, whether .rst or a similar format, potentially rendering this on api.drupal.org using https://github.com/Gregwar/RST or similar.
3. Move long form texts to a new /docs folder in core (and contrib). The folder contains markdown files. Publish the docs via mkdocs or any other static site generator (SSG) that core prefers. See #5
4. Retire the API module and use Doctum or similar external project to generate our API docs. See #5
Remaining tasks
Decide on a option