specialize output for Annotation classes

(Spun off from 📌 Find a consistent way to document plugin types Postponed: needs info , where jhodgdon said I could file this if I feel strongly about it...)

Where D7 has info hooks, D8 has annotations.

On D7, you'd define the hook function, and then return a big array.
On D8, you create a Doctrine annotation inside a PHP comment block, and write what looks more or less like a PHP array inside that.

The documentation for D7 info hooks has a complete list of all the properties of the array that is returned in the hook doxygen block. The API module formats them nicely: https://api.drupal.org/api/drupal/modules!system!system.api.php/function...

Here's how that looks:

This is clearly laid out:
- the array properties are a bullet list, with the property name in bold
- nested arrays are shown as nested bullet lists
- optional properties are marked as such

On D8, these properties are defined in an Annotation class. Instead of the array being outlined in doxygen, each property of the annotation array is a variable in the Annotation class. Documentation for each variable is on the variable itself.

The API module formats this like any other class: https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Entity!Annotation...

This is much harder to read:

- it's a table rather than a list, with columns that aren't relevant to the task at hand
- the property name is prefixed with the class name and a $: 'EntityType::$controllers', so it's harder to scan down the list
- only the first line of description of each property is shown: for more you have to follow the link to the api page for that variable.
- if a property is optional, that's in the variable's typehint. That's not visible on the annotation class page; you have to follow the link to the api page for that variable.
- if a property is a nested array, that's not visible on the class page. You have to follow the link to the api page for that variable.

The full source of the annotation class is available below the table, but that's still not as readable as the D7 version:

- there's no formatting of the text
- there's no linking
- the docblock for each variable starts before the name of the variable it's about, so to connect the long docs about a nested array to the name of the parent property you have to skip back and forth

What I propose is that api module specialize its output of annotation topics. Which is obviously not going to be an easy task, but I think there's a big regression in readability of our docs here. Alternatively, we could change the way we document annotations.