http://www.drupal4hu.com/node/363 has a great explanation that goes some way to demystifying some of the new plugin system.
It would be great if some of this explanation was added to the actual code, as line-by-line comments.
Looking at the the plugin system, I see things like this:
$this->discovery = new AnnotatedClassDiscovery('block', 'block', $namespaces);
$this->discovery = new DerivativeDiscoveryDecorator($this->discovery);
$this->discovery = new AlterDecorator($this->discovery, 'block');
$this->discovery = new CacheDecorator($this->discovery, 'block_plugins:' . language(LANGUAGE_TYPE_INTERFACE)->langcode, 'block', CacheBackendInterface::CACHE_PERMANENT, array('block'));and my brain just GIVES UP. It would be a huge help to me -- and I am certain lots of other Drupal developers -- if each line had a comment to explain what it's doing.