[meta] Block API documentation

Problem/Motivation

The current state of the Block system API documentation is pretty bad:

• The main change record at https://drupal.org/node/1880620 is quite out of date and does not reflect two major rewrites of the API. - Not any more, I rewrote the thing from ground up. chx, 2014 February 24.
• There are numerous very stale issues missing their change records or change record updates:
  • #1927608: Remove the tight coupling between Block Plugins and Block Entities folded into the BAP change notice. chx, 2014 February 24.
  • #2014215: Shift render array defaults back out onto BlockRenderController folded into the BAP change notice. chx, 2014 February 24.
• There are several plugin API changes that might also impact the BAP change record:
  • #2033383: Provide a default plugin bag
  • #2053153: Allow contrib modules to provide plugins on behalf of optional modules
  • #1987298: Shorten directory structure and PSR-0 namespacing for plugins
• The Block API handbook page is just a stub: https://drupal.org/node/2168137
• There are numerous documentation-related followups and @todo, some of which have been outstanding since the original BAP conversion:
  • #1871762: Add detailed documentation explaining the block system's architecture
  • #1874502: Clean up theme demo help in block_help()
  • #2061679: Add a tour for the improved block admin UI at admin/structure/blocks.
  • #1991438: Terminology confusion: 'settings' vs. $configuration

Proposed resolution

Resolve the above issues. Provide handbook, codebase, and change record documentation that will be useful to developers upgrading modules to D8 or creating new D8 modules. Preferably before beta. (I'm tempted to consider this beta-blocking--the change records are independently anyway--but calling it a beta target for now.)

Remaining tasks

1. Write comprehensive handbook and codebase API documentation.
2. Update the relevant change records to show minimal D7 to D8 examples and reference the handbook documentation.
3. Resolve the issues linked above.