>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #2823463. --> Reported by: [joachim](https://www.drupal.org/user/107701) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Drupal used to have a reputation for having enormous arrays. In D8, that's changed, and yet it's stayed the same... we no longer have info hooks, but we still have big arrays for render and Form API, and in addition we now have data structures in annotations and YML files: these are basically the same as arrays.</p> <p>We need to properly document how these data structures work: what can developers create with them and what properties and values they accept.</p> <p>But what makes this challenging is that they are *extensible*: one component invents the structure and uses it, but other components or modules add other properties or values that extend the structure. So we can&rsquo;t document the whole thing in one place, because the complete picture is scattered over various parts of core. But for developers wanting to read about a particular structure, we want all the relevant documentation to be presented in one place.</p> <p>As an example, consider routing.</p> <p>The base routing system is defined in core/lib/Drupal/Core/Routing. That would be a good place to put documentation for MODULE.routing.yml files.</p> <p>But other components are modules go on to define their own properties of routing files:</p> <p>- core/lib/Drupal/Core/Controller invents the _title property and others<br> - core/lib/Drupal/Core/Entity invents _entity_form and others<br> - user module invents _permission<br> - other modules might invent other things!</p> <p>Logically, none of those should be defined in the basic documentation for MODULE.routing.yml files, as the core/lib/Drupal/Core/Routing doesn't depend on them, and shouldn't need to know about them.</p> <p>But a developer who wants to read about routing should be able to read a single document that covers everything -- they shouldn't have to go round piecing together from lots of different documents.</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>I think we need a generic system that lets us tie together the documentation for the base structure, and extra elements that extend it.</p> <p>So this is made up of two things:</p> <p>1. Mark the documentation for the base structure with an ID. (For the time being, leave the matter of how to document a YML file. Let&rsquo;s suppose we have a way of doing that.)<br> 2. Mark the documentation for the extending element:<br> - the ID of the base structure it extends<br> - the position in the structure it can occupy as either a key or a value</p> <p>API module can then stitch all these things together by matching the data structure IDs.</p> <h4>Example 1: routing</h4> <p>There&rsquo;s no set way yet of documenting yml files, but for now let&rsquo;s just assume the core structure is documented somewhere in core/lib/Drupal/Core/Routing.</p> <p>This documentation (whatever it may be, a class docblock, an api.php file, some sort of new api.yml file) gets a doxygen tag:</p> <pre>@datastructure routing</pre><p>Now let&rsquo;s document the various _title properties of routing files. These are invented in core/lib/Drupal/Core/Controller/TitleResolver.php. Suppose we document these in the docblock for that class:</p> <pre>@datastructurekey routing */defaults/ _title<br>&nbsp; Defines a fixed title string for a route.</pre><p>That says that:<br> - we&rsquo;re defining an extra key for a data structure<br> - it belongs to the &lsquo;routing&rsquo; structure<br> - this key goes in the structure tree at */defaults.<br> - the name of the key is _title</p> <h4>Example 2: services file</h4> <p>The main thing that extends the services YML structure is new tags. Same thing as above: the base documentation for a services.yml file gets a tag:</p> <pre>@datastructure services</pre><p>The code that invents a particular tag documents the tag as being part of the services data structure:</p> <pre>@datastructurevalue services services/*/tags mytag<br>&nbsp; Documentation about the tag here..</pre><p>That says that:<br> - we&rsquo;re defining an extra value for a data structure<br> - it belongs to the &lsquo;services&rsquo; structure<br> - this key goes in the structure tree at services/*/tags.<br> - the value is &lsquo;mytag&rsquo;</p> <p>(There&rsquo;s a proposal for those at <a href="https://www.drupal.org/node/2745947">https://www.drupal.org/node/2745947</a>, but the proposal is to invent a new docblock tag just for service tags. I don&rsquo;t think it&rsquo;s maintainable to invent a new docblock tag for each new data structure element we need to document: we&rsquo;ll end up with hundreds of them and API module will need to be taught about each one.)</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <p>- Discuss the proposal<br> - Devise a way to document base structures when these are YML files -- should be in another issue.</p> > Related issue: [Issue #2323895](https://www.drupal.org/node/2323895)