Allow object-based plugin definitions to be created by non-annotated discovery

This is straight forward. Where else in the core can we use it?

++

Note that issues like this should be targeted against 8.4.x, but can be considered for backport once they are committed to that branch. See the updated alpha release policy. Thanks!

We should have an explicit test of this functionality outside of the experimental layout module then. Just in case we remove the experimental module (unlikely though that is).

Also, since this is a move from @internal to not, we should review the entire class, not just the diff.

The code being moved includes this:

  /**
   * The name of the annotation that contains the plugin definition.
   *
   * The class corresponding to this name must implement
   * \Drupal\Component\Annotation\AnnotationInterface.
   *
   * @var string|null
   */
  protected $pluginDefinitionAnnotationName;

  /**
   * ObjectDefinitionDiscoveryDecorator constructor.
   *
   * @param \Drupal\Component\Plugin\Discovery\DiscoveryInterface $decorated
   *   The discovery object that is being decorated.
   * @param string $plugin_definition_annotation_name
   *   The name of the annotation that contains the plugin definition.
   */
  public function __construct(DiscoveryInterface $decorated, $plugin_definition_annotation_name) {
    $this->decorated = $decorated;
    $this->pluginDefinitionAnnotationName = $plugin_definition_annotation_name;
  }

1. I think the comment about AnnotationInterface needs to be in the docs of the constructor. Either in addition to or instead of the docs of the protected property.
2. AnnotationInterface doesn't extend PluginDefinitionInterface or its companions from the other recent issues. Wouldn't that then cause problems? Especially since the default in DefaultPluginManager::__construct() is Drupal\Component\Annotation\Plugin, which also doesn't implement those interfaces. So we might need docs here saying there's in practice additional expectations for $plugin_definition_annotation_name, and we might want to consider changing DefaultPluginManager's default value to something that meets those expectations.

+++ b/core/lib/Drupal/Component/Plugin/Discovery/ObjectDefinitionDiscoveryDecorator.php
@@ -1,20 +1,9 @@
  * Ensures that all array-based definitions are converted to objects.
...
+   *   The name of the annotation that contains the plugin definition. The class
+   *   corresponding to this name must implement
+   *   \Drupal\Component\Annotation\AnnotationInterface.

These two comments are contradictory. If all that's required is that the annotation class implements AnnotationInterface, then its get() method might return either an array or an object. So the statement at the top that ObjectDefinitionDiscoveryDecorator "ensures that all array-based definitions are converted to objects" is incorrect.

This is a task to move the internal api to public so this makes it a feature request and I think we should have a change record for this 'feature request' so that core and contrib can use it as mentioned in #5.

+++ b/core/tests/Drupal/Tests/Component/Annotation/Plugin/Discovery/AnnotationBridgeDecoratorTest.php
@@ -0,0 +1,61 @@
+    $expected = [

Let's add a comment that both discovers are converted to object.

The code looks good. The test looks good. My comments are just minor improvements, can be ignored if someone disagrees, and not commit blocker so RTBC.

Thanks, @jibran! Ticking credit box for review.

Pushed to 8.4.x. Cherry picked to 8.3.x, because it's low disruption and provides a great pattern by which contrib plugin managers can use object definitions with YAML discovery without each such contrib module creating their own solution, like LayoutPluginManager had to do prior to this issue.

Per #18, a CR to inform people of this addition (or maybe a single consolidated CR for all the improvements to using object definitions) would be great. As would be the follow-up to add a comment within the test coverage.