The \Drupal\jsonapi_hypermedia\Annotation\JsonapiHypermediaLinkProvider annotation

Concern 1: class-level documentation

Class-level documentation is incomplete.

For examples, see the class-level docblocks at:

• \Drupal\editor\Annotation\Editor
• \Drupal\Core\Layout\Annotation\Layout
• \Drupal\rest\Annotation\RestResource
• …

Concern 2: annotation keys that aren't technically allowed

For example, \Drupal\jsonapi_hypermedia\Plugin\Derivative\EntityPublishedLinkProvider::getDerivativeDefinitions() generates the following annotation keys:

• link_key → ✅ because it is described by the annotation
• link_context → ✅ because it is described by the annotation
• operation → ❌ because it is NOT described by the annotation
• published_entity_key → ❌ because it is NOT described by the annotation

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.

What if Drupal core starts validating annotations in the future?

I looked at the published_entity_key example in detail. In principle it's possible to live without this, but the consequence then is a costly $entity->getEntityType()->getKey('published') 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.
_{Usually, I would argue this is premature optimization. But $entity->getEntityType() will only incur an expensive lookup once 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 not calling this premature optimization.}

Concern 3: all examples in the module use derivers

It'd be good to have at least one example not use a deriver. Even if it's a test one.