From fe3629cdeb11fc81b7500ba8ea8588c0f03c26e7 Mon Sep 17 00:00:00 2001
From: David Buchmann <david.buchmann@liip.ch>
Date: Mon, 18 Dec 2017 17:32:00 +0100
Subject: [PATCH] WIP parse phpdoc annotations in jms models

---
 ModelDescriber/JMSModelDescriber.php      |  2 +
 ModelDescriber/PhpdocAnnotationReader.php | 61 +++++++++++++++++++++++
 README.md                                 |  2 +-
 3 files changed, 64 insertions(+), 1 deletion(-)
 create mode 100644 ModelDescriber/PhpdocAnnotationReader.php

diff --git a/ModelDescriber/JMSModelDescriber.php b/ModelDescriber/JMSModelDescriber.php
index 6e81f13..a4ae751 100644
--- a/ModelDescriber/JMSModelDescriber.php
+++ b/ModelDescriber/JMSModelDescriber.php
@@ -103,6 +103,8 @@ class JMSModelDescriber implements ModelDescriberInterface, ModelRegistryAwareIn
 
             // read property options from Swagger Property annotation if it exists
             if (null !== $item->reflection) {
+                $phpdocReader = new PhpdocAnnotationReader();
+                $phpdocReader->updateWithPhpdoc($item->reflection, $realProp);
                 $this->swaggerPropertyAnnotationReader->updateWithSwaggerPropertyAnnotation($item->reflection, $realProp);
             }
         }
diff --git a/ModelDescriber/PhpdocAnnotationReader.php b/ModelDescriber/PhpdocAnnotationReader.php
new file mode 100644
index 0000000..83fb1f1
--- /dev/null
+++ b/ModelDescriber/PhpdocAnnotationReader.php
@@ -0,0 +1,61 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\ModelDescriber;
+
+use EXSyst\Component\Swagger\Schema;
+use EXSyst\Component\Swagger\Items;
+use phpDocumentor\Reflection\DocBlock\Tags\Var_;
+use phpDocumentor\Reflection\DocBlockFactory;
+use phpDocumentor\Reflection\DocBlockFactoryInterface;
+
+/**
+ * @internal
+ */
+class PhpdocAnnotationReader
+{
+    private $docBlockFactory;
+
+    public function __construct(DocBlockFactoryInterface $docBlockFactory = null)
+    {
+        if (null === $docBlockFactory) {
+            $docBlockFactory = DocBlockFactory::createInstance();
+        }
+        $this->docBlockFactory = $docBlockFactory;
+    }
+
+    /**
+     * @param \ReflectionProperty $reflectionProperty
+     * @param Items|Schema        $property
+     */
+    public function updateWithPhpdoc(\ReflectionProperty $reflectionProperty, $property)
+    {
+        try {
+            $docBlock = $this->docBlockFactory->create($reflectionProperty);
+            if (!$title = $docBlock->getSummary()) {
+                /** @var Var_ $var */
+                foreach ($docBlock->getTagsByName('var') as $var) {
+                    if (null === $description = $var->getDescription()) continue;
+                    $title = $description->render();
+                    if ($title) break;
+                }
+            }
+            if ($property->getTitle() === null && $title) {
+                $property->setTitle($title);
+            }
+            if ($property->getDescription() === null && $docBlock->getDescription()) {
+                $property->setDescription($docBlock->getDescription()->render());
+            }
+        } catch (\Exception $e) {
+            // ignore
+        }
+    }
+}
diff --git a/README.md b/README.md
index 0b76436..4030c6f 100644
--- a/README.md
+++ b/README.md
@@ -151,7 +151,7 @@ serialization groups when using the Symfony serializer.
 ### If you're using the JMS Serializer
 
 The metadata of the JMS serializer are used by default to describe your
-models. Note that PHP doc blocks aren't supported in this case.
+models.
 
 In case you prefer using the [Symfony PropertyInfo component](https://symfony.com/doc/current/components/property_info.html) (you
 won't be able to use JMS serialization groups), you can disable JMS serializer