Problem/Motivation
Unlike many other pages of core documentation, the Block API documentation doesn't contain a worked example.
Compare:
* https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Menu%21me...
* https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Routing%2...
* https://api.drupal.org/api/drupal/core%21core.api.php/group/form_api/8.2.x
* https://api.drupal.org/api/drupal/core%21modules%21block%21block.api.php...
While the Block API documentation links off to examples elsewhere in a contrib module, this is probably not great practice (and definitely not consistent with the other API docs.)
Proposed resolution
Add an example to block.api.php
Add sections.
Do not remove references to \Drupal\Core\Block\Annotation\Block. let's do that in a separate issue
Remaining tasks
Review
Commit
User interface changes
None.
API changes
None.
Data model changes
None.