Add a dedicated @EntityReferenceSelection annotation

Completed the @todos and also fixed some doxygen while I was there. I hope I explained the grouping stuff well enough..

#2: entity-reference-selection-2016589-2.patch queued for re-testing.

Well, it is your decision whether you want to port all the docs in this issue.

+++ b/core/modules/entity_reference/lib/Drupal/entity_reference/Plugin/Type/SelectionPluginManager.phpundefined
@@ -28,8 +28,11 @@ class SelectionPluginManager extends PluginManagerBase {
+    $annotation_namespaces = array('Drupal\entity_reference\Annotation' => $namespaces['Drupal\entity_reference']);
+    $this->discovery = new AnnotatedClassDiscovery('entity_reference/selection', $namespaces, $annotation_namespaces, 'Drupal\entity_reference\Annotation\EntityReferenceSelection');
+    $this->discovery = new AlterDecorator($this->discovery, 'entity_reference_selection');
+    $this->discovery = new CacheDecorator($this->discovery, 'entity_reference_selection');

Just wondering whether the DefaultPluginManagerBase could be used here as well.

Huh? There was nothing to port, that documentation didn't exist..

I was talking about all the @inheritdoc instances.

Well, it has to happen at some point, so I think a small patch like this is the perfect opportunity.

Updated the patch to use DefaultPluginManager :)

So it seems that DefaultPluginManager's constructor doesn't really work for us, this should be better.

+++ b/core/modules/entity_reference/lib/Drupal/entity_reference/Plugin/Type/SelectionPluginManager.phpundefined
@@ -9,28 +9,31 @@
+    $this->subdir = 'entity_reference/selection';
...
+    $this->discovery = new AnnotatedClassDiscovery($this->subdir, $namespaces, $annotation_namespaces, 'Drupal\entity_reference\Annotation\EntityReferenceSelection');

We don't want to have a derivative discovery here, as according to amateescu this caused issues here.

+++ b/core/modules/entity_reference/lib/Drupal/entity_reference/Plugin/Type/SelectionPluginManager.phpundefined
@@ -9,28 +9,31 @@
   /**
-   * Constructs a SelectionPluginManager object.
-   *
-   * @param \Traversable $namespaces
-   *   An object that implements \Traversable which contains the root paths
-   *   keyed by the corresponding namespace to look for plugin implementations,
+   * {@inheritdoc}
    */
-  public function __construct(\Traversable $namespaces) {
-    $this->baseDiscovery = new AlterDecorator(new AnnotatedClassDiscovery('entity_reference/selection', $namespaces), 'entity_reference_selection');
-    $this->discovery = new CacheDecorator($this->baseDiscovery, 'entity_reference_selection');
+  public function __construct(\Traversable $namespaces, CacheBackendInterface $cache_backend, LanguageManager $language_manager, ModuleHandlerInterface $module_handler) {

We need to document why we are doing this.

Sure thing ;)

Rerolled after #2020405: Correct misspelling of 'referenceable'.

This issue was RTBC and passing tests on July 1, the beginning of API freeze.

Committed 1b0d6ac and pushed to 8.x. Thanks!