Use DocBlock classes, add return type hint and allow override of doc block

Author: sandrokeil

src/Code/MethodGenerator.php

@@ -10,6 +10,9 @@
 
 namespace OpenCodeModeling\CodeAst\Code;
 
+use OpenCodeModeling\CodeAst\Code\DocBlock\DocBlock;
+use OpenCodeModeling\CodeAst\Code\DocBlock\Tag\ParamTag;
+use OpenCodeModeling\CodeAst\Code\DocBlock\Tag\ReturnTag;
 use OpenCodeModeling\CodeAst\Exception;
 use PhpParser\Comment\Doc;
 use PhpParser\Node\Stmt\ClassMethod;
@@ -49,6 +52,16 @@ final class MethodGenerator extends AbstractMemberGenerator
      */
     private $docBlockComment;
 
+    /**
+     * @var string|null
+     */
+    private $returnTypeDocBlockHint;
+
+    /**
+     * @var DocBlock|null
+     */
+    private $docBlock;
+
     /**
      * @param string $name
      * @param array $parameters
@@ -154,7 +167,7 @@ public function getReturnType(): ?TypeGenerator
         return $this->returnType;
     }
 
-    public function docBlockComment(): ?string
+    public function getDocBlockComment(): ?string
     {
         return $this->docBlockComment;
     }
@@ -164,10 +177,20 @@ public function setDocBlockComment(?string $docBlockComment): void
         $this->docBlockComment = $docBlockComment;
     }
 
+    public function getReturnTypeDocBlockHint(): ?string
+    {
+        return $this->returnTypeDocBlockHint;
+    }
+
+    public function setReturnTypeDocBlockHint(?string $typeDocBlockHint): void
+    {
+        $this->returnTypeDocBlockHint = $typeDocBlockHint;
+    }
+
     /**
      * @return bool
      */
-    public function typed(): bool
+    public function getTyped(): bool
     {
         return $this->typed;
     }
@@ -180,46 +203,18 @@ public function setTyped(bool $typed): void
         $this->typed = $typed;
     }
 
-    public function generate(): ClassMethod
+    /**
+     * Ignores generation of the doc block and uses provided doc block instead.
+     *
+     * @param DocBlock $docBlock
+     */
+    public function overrideDocBlock(DocBlock $docBlock): void
     {
-        $docBlockTypes = [];
-
-        foreach ($this->getParameters() as $parameter) {
-            if (null === $parameter->getType()) {
-                $type = 'mixed';
-            } else {
-                $type = $parameter->getType()->isNullable()
-                    ? $parameter->getType()->type() . '|null'
-                    : $parameter->getType()->type();
-            }
-
-            if ($typeHint = $parameter->getTypeDocBlockHint()) {
-                $type = $typeHint;
-            }
-
-            $docBlockTypes[] = '@var ' . $type .  ' $' . $parameter->getName();
-        }
-
-        $methodComment = "/**\n";
-
-        if ($this->docBlockComment) {
-            $multiLineDocBlockComment = \trim(\preg_replace("/\n/", "\n * ", $this->docBlockComment));
-
-            $methodComment .= " * {$multiLineDocBlockComment}\n *";
-        }
-
-        foreach ($docBlockTypes as $docBlockType) {
-            $methodComment .= "\n * " . $docBlockType;
-        }
-
-        $methodComment = \preg_replace("/ \* \n/", " *\n", $methodComment) . "\n */";
-
-        $attributes = [];
-
-        if ($this->typed === false || $this->docBlockComment) {
-            $attributes = ['comments' => [new Doc($methodComment)]];
-        }
+        $this->docBlock = $docBlock;
+    }
 
+    public function generate(): ClassMethod
+    {
         return new ClassMethod(
             $this->getName(),
             [
@@ -233,10 +228,51 @@ static function (ParameterGenerator $parameter) {
                 'stmts' => $this->body ? $this->body->generate() : null,
                 'returnType' => $this->returnType ? $this->returnType->generate() : null,
             ],
-            $attributes
+            $this->generateAttributes()
         );
     }
 
+    private function generateAttributes(): array
+    {
+        $attributes = [];
+
+        if ($this->docBlock) {
+            return ['comments' => [new Doc($this->docBlock->generate())]];
+        }
+
+        if ($this->typed === false || $this->docBlockComment || $this->returnTypeDocBlockHint) {
+            $docBlock = new DocBlock($this->docBlockComment);
+
+            foreach ($this->getParameters() as $parameter) {
+                if (null === $parameter->getType()) {
+                    $types = 'mixed';
+                } else {
+                    $types = $parameter->getType()->types();
+                }
+                if ($typeHint = $parameter->getTypeDocBlockHint()) {
+                    $types = $typeHint;
+                }
+                $docBlock->addTag(new ParamTag($parameter->getName(), $types));
+            }
+
+            $returnType = null;
+
+            if ($this->returnType) {
+                $returnType = $this->returnType->type();
+            }
+            if ($this->returnTypeDocBlockHint) {
+                $returnType = $this->returnTypeDocBlockHint;
+            }
+            if ($returnType) {
+                $docBlock->addTag(new ReturnTag($returnType));
+            }
+
+            $attributes = ['comments' => [new Doc($docBlock->generate())]];
+        }
+
+        return $attributes;
+    }
+
     public function withoutBody(): self
     {
         $self = clone $this;

src/Code/TypeGenerator.php

@@ -118,6 +118,22 @@ public function isNullable(): bool
         return $this->nullable;
     }
 
+    /**
+     * Normally only one type. Additionally the type null if nullable.
+     *
+     * @return string[]
+     */
+    public function types(): array
+    {
+        $types = [$this->type];
+
+        if ($this->nullable) {
+            $types[] = 'null';
+        }
+
+        return $types;
+    }
+
     public function generate(): NodeAbstract
     {
         $type = $this->isInternalPhpType

tests/Code/MethodGeneratorTest.php

@@ -4,6 +4,7 @@
 
 namespace OpenCodeModelingTest\CodeAst\Code;
 
+use OpenCodeModeling\CodeAst\Code\DocBlock\DocBlock;
 use OpenCodeModeling\CodeAst\Code\MethodGenerator;
 use OpenCodeModeling\CodeAst\Code\ParameterGenerator;
 use PhpParser\Parser;
@@ -52,6 +53,49 @@ public function setType(?string $type) : void;
         $this->assertSame($expectedOutput, $this->printer->prettyPrintFile([$method->generate()]));
     }
 
+    /**
+     * @test
+     */
+    public function it_generates_method_with_doc_block_if_typed(): void
+    {
+        $method = new MethodGenerator('getItems');
+        $method->setReturnTypeDocBlockHint('Items[]');
+        $method->setReturnType('array');
+
+        $expectedOutput = <<<'EOF'
+<?php
+
+/**
+ * @return Items[]
+ */
+public function getItems() : array;
+EOF;
+
+        $this->assertSame($expectedOutput, $this->printer->prettyPrintFile([$method->generate()]));
+    }
+
+    /**
+     * @test
+     */
+    public function it_generates_method_with_overridden_doc_block(): void
+    {
+        $method = new MethodGenerator('getItems');
+        $method->setReturnTypeDocBlockHint('Items[]');
+        $method->setReturnType('array');
+        $method->overrideDocBlock(new DocBlock('Awesome'));
+
+        $expectedOutput = <<<'EOF'
+<?php
+
+/**
+ * Awesome
+ */
+public function getItems() : array;
+EOF;
+
+        $this->assertSame($expectedOutput, $this->printer->prettyPrintFile([$method->generate()]));
+    }
+
     /**
      * @test
      */
@@ -72,7 +116,7 @@ public function it_generates_method_with_doc_block_comment_if_typed(): void
 /**
  * Sets an awesome type
  *
- * @var string|null $type
+ * @param string|null $type
  */
 public function setType(?string $type);
 EOF;
@@ -83,14 +127,15 @@ public function setType(?string $type);
     /**
      * @test
      */
-    public function it_generates_method_with_doc_block(): void
+    public function it_generates_method_with_doc_block_comment(): void
     {
         $method = new MethodGenerator(
             'setType',
             [
                 new ParameterGenerator('type', '?string'),
             ]
         );
+        $method->setReturnType('void');
         $method->setDocBlockComment('Sets an awesome type');
         $method->setTyped(true);
 
@@ -100,9 +145,10 @@ public function it_generates_method_with_doc_block(): void
 /**
  * Sets an awesome type
  *
- * @var string|null $type
+ * @param string|null $type
+ * @return void
  */
-public function setType(?string $type);
+public function setType(?string $type) : void;
 EOF;
 
         $this->assertSame($expectedOutput, $this->printer->prettyPrintFile([$method->generate()]));
@@ -119,15 +165,14 @@ public function it_generates_method_with_mixed_type_doc_block(): void
                 new ParameterGenerator('type'),
             ]
         );
-        $method->setDocBlockComment('Sets an awesome type');
+        $method->setReturnTypeDocBlockHint('mixed');
 
         $expectedOutput = <<<'EOF'
 <?php
 
 /**
- * Sets an awesome type
- *
- * @var mixed $type
+ * @param mixed $type
+ * @return mixed
  */
 public function setType($type);
 EOF;
@@ -149,6 +194,7 @@ public function it_generates_method_with_array_type_doc_block(): void
                 $parameter,
             ]
         );
+        $method->setReturnType('void');
         $method->setDocBlockComment('Sets awesome items');
 
         $expectedOutput = <<<'EOF'
@@ -157,9 +203,10 @@ public function it_generates_method_with_array_type_doc_block(): void
 /**
  * Sets awesome items
  *
- * @var array<string, \stdClass> $items
+ * @param array<string, \stdClass> $items
+ * @return void
  */
-public function setItems(array $items);
+public function setItems(array $items) : void;
 EOF;
 
         $this->assertSame($expectedOutput, $this->printer->prettyPrintFile([$method->generate()]));
@@ -202,8 +249,8 @@ public function it_generates_method_with_long_doc_block(): void
  * It is a long established fact that a reader will be distracted by the readable content of a page when looking at
  * its layout.
  *
- * @var string $type
- * @var int|null $value
+ * @param string $type
+ * @param int|null $value
  */
 public function setType(string $type, ?int $value);
 EOF;