>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3077985. --> Reported by: [wim leers](https://www.drupal.org/user/99777) >>> <h3>Concern 1: class-level documentation</h3> <p>Class-level documentation is incomplete.</p> <p>For examples, see the class-level docblocks at:</p> <ul> <li><code>\Drupal\editor\Annotation\Editor</code></li> <li><code>\Drupal\Core\Layout\Annotation\Layout</code></li> <li><code>\Drupal\rest\Annotation\RestResource</code></li> <li>&hellip;</li> </ul> <h3>Concern 2: annotation keys that aren't technically allowed</h3> <p>For example, <code>\Drupal\jsonapi_hypermedia\Plugin\Derivative\EntityPublishedLinkProvider::getDerivativeDefinitions()</code> generates the following annotation keys:</p> <ul> <li><code>link_key</code> &rarr; &#9989; because it is described by the annotation</li> <li><code>link_context</code> &rarr; &#9989; because it is described by the annotation</li> <li><code>operation</code> &rarr; &#10060; because it is NOT described by the annotation</li> <li><code>published_entity_key</code> &rarr; &#10060; because it is NOT described by the annotation</li> </ul> <p>I think I mentioned this before when we looked at an early PoC together. I don't remember the outcome. If we're going to keep it like this, this at least needs be documented explicitly.</p> <p>What if Drupal core starts validating annotations in the future?</p> <p>I looked at the <code>published_entity_key</code> example in detail. In principle it's possible to live without this, but the consequence then is a costly <code>$entity-&gt;getEntityType()-&gt;getKey('published')</code> lookup for every resource object. I see how incurring this cost once at build time instead of N times at run time is appealing. I'm fine with doing it at build time. But I am concerned about putting arbitrary keys in the annotation.<br> _{Usually, I would argue this is premature optimization. But <code>$entity-&gt;getEntityType()</code> will only incur an expensive lookup <em>once</em> per request per entity type, subsequent calls hit a static cache. Although it requires many function calls to reach that static cache. Which is why I'm leaning towards <em>not</em> calling this premature optimization.}</p> <h3>Concern 3: all examples in the module use derivers</h3> <p>It'd be good to have at least one example not use a deriver. Even if it's a test one.</p>