Extract summary and description based on the phpdoc spec.

Changelog.md

@@ -1,5 +1,8 @@
 # Changelog
 
+ - Augment Operations summary and description based on the comment. #293
+ - Bugfixes #300
+
 ## 2.0.7
 
  - Add support for xml (and externalDocs and properties) inside a @SWG\Items. #279

src/Context.php

@@ -162,12 +162,57 @@ public function __debugInfo()
     }
 
     /**
+     * A short piece of text, usually one line, providing the basic function of the associated element.
      * @return string|null
      */
-    public function extractDescription()
+    public function phpdocSummary()
+    {
+        $content = $this->phpdocContent();
+        if (!$content) {
+            return null;
+        }
+        $lines = explode("\n", $content);
+        $summary = '';
+        foreach ($lines as $line) {
+            $summary .= $line."\n";
+            if ($line === '' || substr($line, -1) === '.') {
+                return trim($summary);
+            }
+        }
+        $summary = trim($summary);
+        if ($summary === '') {
+            return null;
+        }
+        return $summary;
+    }
+
+    /**
+     * An optional longer piece of text providing more details on the associated element’s function. This is very useful when working with a complex element.
+     * @return string|null
+     */
+    public function phpdocDescription()
+    {
+        $summary = $this->phpdocSummary();
+        if (!$summary) {
+            return null;
+        }
+        $description = trim(substr($this->phpdocContent(), strlen($summary)));
+        if ($description === '') {
+            return null;
+        }
+        return $description;
+    }
+
+    /**
+     * The text contents of the phpdoc comment (excl. tags)
+     * @return string|null
+     */
+    public function phpdocContent()
     {
         $comment = explode("\n", $this->comment);
-        unset($comment[0]);
+        $comment[0] = preg_replace('/[ \t]*\\/\*\*/', '', $comment[0]); // strip '/**'
+        $i = count($comment) -1;
+        $comment[$i] = preg_replace('/\*\/[ \t]*$/', '', $comment[$i]); // strip '*/'
         $lines = [];
         $append = false;
         foreach ($comment as $line) {
@@ -187,9 +232,6 @@ public function extractDescription()
         if ($description === '') {
             return null;
         }
-        if (stripos($description, 'license')) {
-            return null; // Don't use the GPL/MIT license text as the description.
-        }
         return $description;
     }
 

src/Processors/AugmentOperations.php

@@ -20,34 +20,12 @@ public function __invoke(Analysis $analysis)
 
         /** @var Operation $operation */
         foreach ($allOperations as $operation) {
-            $context = $this->splitDescription($operation->_context->extractDescription());
-
-            if (null === $operation->summary && $context['summary']) {
-                $operation->summary = $context['summary'];
+            if (null === $operation->summary) {
+                $operation->summary = $operation->_context->phpdocSummary();
             }
-            if (null === $operation->description && $context['description']) {
-                $operation->description = $context['description'];
+            if (null === $operation->description) {
+                $operation->description = $operation->_context->phpdocDescription();
             }
         }
     }
-
-    /**
-     * @param string $description
-     *
-     * @return string[]
-     */
-    private function splitDescription($description)
-    {
-        if (!$description) {
-            return ['summary' => '', 'description' => ''];
-        }
-        $lines = explode("\n", $description, 3);
-        if (count($lines) == 1) {
-            return ['summary' => $description, 'description' => ''];
-        }
-        if (count($lines) == 3 && $lines[1] === '') { // Single line summary - blank line - description
-            return ['summary' => $lines[0], 'description' => $lines[2]];
-        }
-        return ['summary' => '', 'description' => $description];
-    }
 }

src/Processors/AugmentProperties.php

@@ -88,7 +88,7 @@ public function __invoke(Analysis $analysis)
                 }
             }
             if ($property->description === null) {
-                $property->description = $context->extractDescription();
+                $property->description = $context->phpdocContent();
             }
         }
     }

tests/ContextTest.php

@@ -26,7 +26,7 @@ public function testDetect()
 
     public function testFullyQualifiedName()
     {
-        $swagger = \Swagger\scan(__DIR__ . '/Fixtures/Customer.php');
+        $swagger = \Swagger\scan(__DIR__.'/Fixtures/Customer.php');
         $context = $swagger->definitions[0]->_context;
         // resolve with namespace
         $this->assertSame('\FullyQualified', $context->fullyQualifiedName('\FullyQualified'));
@@ -40,8 +40,8 @@ public function testFullyQualifiedName()
         $this->assertSame('\Swagger\Logger', $context->fullyQualifiedName('SwgLogger'));
         $this->assertSame('\Swagger\Annotations\QualifiedAlias', $context->fullyQualifiedName('SWG\QualifiedAlias'));
     }
-    
-    public function testExtractDescription()
+
+    public function testPhpdocContent()
     {
         $singleLine = new Context(['comment' => <<<END
     /**
@@ -51,8 +51,8 @@ public function testExtractDescription()
      */
 END
         ]);
-        $this->assertEquals('A single line.', $singleLine->extractDescription());
-        
+        $this->assertEquals('A single line.', $singleLine->phpdocContent());
+
         $multiline = new Context(['comment' => <<<END
 /**
  * A description spread across
@@ -64,8 +64,8 @@ public function testExtractDescription()
  */
 END
         ]);
-        $this->assertEquals("A description spread across\nmultiple lines.\n\neven blank lines", $multiline->extractDescription());
-        
+        $this->assertEquals("A description spread across\nmultiple lines.\n\neven blank lines", $multiline->phpdocContent());
+
         $escapedLinebreak = new Context(['comment' => <<<END
 /**
  * A single line spread across \
@@ -75,6 +75,42 @@ public function testExtractDescription()
  */
 END
         ]);
-        $this->assertEquals("A single line spread across multiple lines.", $escapedLinebreak->extractDescription());
+        $this->assertEquals("A single line spread across multiple lines.", $escapedLinebreak->phpdocContent());
+    }
+
+    /**
+     * https://phpdoc.org/docs/latest/guides/docblocks.html
+     */
+    public function testPhpdocSummaryAndDescription()
+    {
+        $single = new Context(['comment' => '/** This is a single line DocComment. */']);
+        $this->assertEquals('This is a single line DocComment.', $single->phpdocContent());
+        $multi = new Context(['comment' => "/**\n * This is a multi-line DocComment.\n */"]);
+        $this->assertEquals('This is a multi-line DocComment.', $multi->phpdocContent());
+
+        $emptyWhiteline = new Context(['comment' => <<<END
+/**
+ * This is a summary
+ *
+ * This is a description
+ */
+END
+        ]);
+        $this->assertEquals('This is a summary', $emptyWhiteline->phpdocSummary());
+        $periodNewline = new Context(['comment' => <<<END
+     /**
+     * This is a summary.
+     * This is a description
+     */
+END
+        ]);
+        $this->assertEquals('This is a summary.', $periodNewline->phpdocSummary());
+        $multilineSummary = new Context(['comment' => <<<END
+     /**
+     * This is a summary
+     * but this is part of the summary
+     */
+END
+        ]);
     }
 }