Issue #2945789 by jcisio, ravi.shankar, joachim, kristiaanvandeneynde, jungle,...

Issue #2945789 by jcisio, ravi.shankar, joachim, kristiaanvandeneynde, jungle, alexpott: Document quirks of Entity reference selection plugins while a fix is figured out

(cherry picked from commit 96dad7dc)

core/lib/Drupal/Core/Entity/Annotation/EntityReferenceSelection.php

@@ -23,6 +23,11 @@ class EntityReferenceSelection extends Plugin {
   /**
    * The plugin ID.
    *
+   * There are some implementation bugs that make the plugin available only if
+   * the ID follows a specific pattern. It must be either identical to group or
+   * prefixed with the group. E.g. if the group is "foo" the ID must be either
+   * "foo" or "foo:bar".
+   *
    * @var string
    */
   public $id;
@@ -44,7 +49,7 @@ class EntityReferenceSelection extends Plugin {
    * For example, if we want to override the NodeSelection from the 'default'
    * selection type, we can define the annotation of a new plugin as follows:
    * @code
-   * id = "node_advanced",
+   * id = "default:node_advanced",
    * entity_types = {"node"},
    * group = "default",
    * weight = 5
@@ -65,6 +70,8 @@ class EntityReferenceSelection extends Plugin {
   /**
    * The weight of the plugin in its group.
    *
+   * This property is used to select the "best" plugin within a group.
+   *
    * @var int
    */
   public $weight;