feature #28117 [FrameworkBundle] add class description to debug:container command (gimler)

This PR was merged into the 4.2-dev branch.

Discussion
----------

[FrameworkBundle] add class description to debug:container command

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| License       | MIT
| Doc PR        | symfony/symfony-docs#... <!-- required for new features -->

Our developer finds it useful when the `console debug:container <service>` command print out the class description.

![bildschirmfoto vom 2018-08-02 14-22-17](https://user-images.githubusercontent.com/200904/43583449-d4bf74e4-965f-11e8-8e88-0db8017c5a90.png)

* [x] json
* [x] txt
* [x] xml
* [x] md

Commits
-------

5fc6155225 [FrameworkBundle] add class description to debug:container command

src/Symfony/Bundle/FrameworkBundle/Console/Descriptor/Descriptor.php

@@ -11,6 +11,8 @@
 
 namespace Symfony\Bundle\FrameworkBundle\Console\Descriptor;
 
+use phpDocumentor\Reflection\DocBlockFactory;
+use phpDocumentor\Reflection\DocBlockFactoryInterface;
 use Symfony\Component\Console\Descriptor\DescriptorInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\DependencyInjection\Alias;
@@ -284,4 +286,29 @@ abstract class Descriptor implements DescriptorInterface
 
         return $serviceIds;
     }
+
+    /**
+     * Get class description from doc block.
+     *
+     * @param string $class
+     *
+     * @return string
+     */
+    protected function getClassDescription($class)
+    {
+        if (!interface_exists(DocBlockFactoryInterface::class)) {
+            return '';
+        }
+
+        try {
+            $reflectionProperty = new \ReflectionClass($class);
+
+            return DocBlockFactory::createInstance()
+                ->create($reflectionProperty->getDocComment())
+                ->getSummary();
+        } catch (\ReflectionException $e) {
+        }
+
+        return '';
+    }
 }

src/Symfony/Bundle/FrameworkBundle/Console/Descriptor/JsonDescriptor.php

@@ -220,6 +220,10 @@ class JsonDescriptor extends Descriptor
             'autoconfigure' => $definition->isAutoconfigured(),
         );
 
+        if ('' !== $classDescription = $this->getClassDescription($definition->getClass())) {
+            $data['description'] = $classDescription;
+        }
+
         if ($showArguments) {
             $data['arguments'] = $this->describeValue($definition->getArguments(), $omitTags, $showArguments);
         }

src/Symfony/Bundle/FrameworkBundle/Console/Descriptor/MarkdownDescriptor.php

@@ -181,7 +181,13 @@ class MarkdownDescriptor extends Descriptor
      */
     protected function describeContainerDefinition(Definition $definition, array $options = array())
     {
-        $output = '- Class: `'.$definition->getClass().'`'
+        $output = '';
+
+        if ('' !== $classDescription = $this->getClassDescription($definition->getClass())) {
+            $output .= '- Description: `'.$classDescription.'`'."\n";
+        }
+
+        $output .= '- Class: `'.$definition->getClass().'`'
             ."\n".'- Public: '.($definition->isPublic() && !$definition->isPrivate() ? 'yes' : 'no')
             ."\n".'- Synthetic: '.($definition->isSynthetic() ? 'yes' : 'no')
             ."\n".'- Lazy: '.($definition->isLazy() ? 'yes' : 'no')

src/Symfony/Bundle/FrameworkBundle/Console/Descriptor/TextDescriptor.php

@@ -260,6 +260,10 @@ class TextDescriptor extends Descriptor
             $options['output']->title(sprintf('Information for Service "<info>%s</info>"', $options['id']));
         }
 
+        if ('' !== $classDescription = $this->getClassDescription($definition->getClass())) {
+            $options['output']->text($classDescription."\n");
+        }
+
         $tableHeaders = array('Option', 'Value');
 
         $tableRows[] = array('Service ID', isset($options['id']) ? $options['id'] : '-');

src/Symfony/Bundle/FrameworkBundle/Console/Descriptor/XmlDescriptor.php

@@ -304,6 +304,11 @@ class XmlDescriptor extends Descriptor
             $serviceXML->setAttribute('id', $id);
         }
 
+        if ('' !== $classDescription = $this->getClassDescription($definition->getClass())) {
+            $serviceXML->appendChild($descriptionXML = $dom->createElement('description'));
+            $descriptionXML->appendChild($dom->createCDATASection($classDescription));
+        }
+
         $serviceXML->setAttribute('class', $definition->getClass());
 
         if ($factory = $definition->getFactory()) {

src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/builder_1_arguments.json

@@ -76,6 +76,7 @@
             "abstract": false,
             "autowire": false,
             "autoconfigure": false,
+            "description": "ContainerInterface is the interface implemented by service container classes.",
             "arguments": [],
             "file": null,
             "tags": []

src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/builder_1_arguments.md

@@ -20,6 +20,7 @@ Definitions
 
 ### service_container
 
+- Description: `ContainerInterface is the interface implemented by service container classes.`
 - Class: `Symfony\Component\DependencyInjection\ContainerInterface`
 - Public: yes
 - Synthetic: yes

src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/builder_1_arguments.xml

@@ -23,5 +23,7 @@
       <argument type="service" id=".definition_2"/>
     </argument>
   </definition>
-  <definition id="service_container" class="Symfony\Component\DependencyInjection\ContainerInterface" public="true" synthetic="true" lazy="false" shared="true" abstract="false" autowired="false" autoconfigured="false" file=""/>
+  <definition id="service_container" class="Symfony\Component\DependencyInjection\ContainerInterface" public="true" synthetic="true" lazy="false" shared="true" abstract="false" autowired="false" autoconfigured="false" file="">
+    <description><![CDATA[ContainerInterface is the interface implemented by service container classes.]]></description>
+  </definition>
 </container>

src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/builder_1_public.json

@@ -23,6 +23,7 @@
             "abstract": false,
             "autowire": false,
             "autoconfigure": false,
+            "description": "ContainerInterface is the interface implemented by service container classes.",
             "file": null,
             "tags": []
         }

src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/builder_1_public.md

@@ -19,6 +19,7 @@ Definitions
 
 ### service_container
 
+- Description: `ContainerInterface is the interface implemented by service container classes.`
 - Class: `Symfony\Component\DependencyInjection\ContainerInterface`
 - Public: yes
 - Synthetic: yes

src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/builder_1_public.xml

@@ -4,5 +4,7 @@
   <definition id="definition_1" class="Full\Qualified\Class1" public="true" synthetic="false" lazy="true" shared="true" abstract="true" autowired="false" autoconfigured="false" file="">
     <factory class="Full\Qualified\FactoryClass" method="get"/>
   </definition>
-  <definition id="service_container" class="Symfony\Component\DependencyInjection\ContainerInterface" public="true" synthetic="true" lazy="false" shared="true" abstract="false" autowired="false" autoconfigured="false" file=""/>
+  <definition id="service_container" class="Symfony\Component\DependencyInjection\ContainerInterface" public="true" synthetic="true" lazy="false" shared="true" abstract="false" autowired="false" autoconfigured="false" file="">
+    <description><![CDATA[ContainerInterface is the interface implemented by service container classes.]]></description>
+  </definition>
 </container>

src/Symfony/Bundle/FrameworkBundle/composer.json

@@ -78,6 +78,7 @@
     },
     "suggest": {
         "ext-apcu": "For best performance of the system caches",
+        "phpdocumentor/reflection-docblock": "For display additional information in debug:container",
         "symfony/console": "For using the console commands",
         "symfony/form": "For using forms",
         "symfony/serializer": "For using the serializer service",