Improve API

API/danog/PhpDoc/PhpDocBuilder.md

@@ -1,6 +1,6 @@
 ---
-title: danog\PhpDoc\PhpDocBuilder: PHP documentation builder.
+title: "danog\\PhpDoc\\PhpDocBuilder: PHP documentation builder."
-description: 
+description: ""
 
 ---
 # `danog\PhpDoc\PhpDocBuilder`
@@ -14,8 +14,6 @@ PHP documentation builder.
 
 
 
----
-Generated by [danog/phpdoc](https://phpdoc.daniil.it).  
 ## Method list:
 * `fromNamespace(string $namespace): self`
 * `setAuthors(\phpDocumentor\Reflection\DocBlock\Tags\Author[] $authors): self`
@@ -25,6 +23,8 @@ Generated by [danog/phpdoc](https://phpdoc.daniil.it).
 * `setName(string $name): self`
 * `setDescription(string $description): self`
 * `setImage(string $image): self`
+* `addFrontMatter(string $key, string $value): self`
+* `addIndexFrontMatter(string $key, string $value): self`
 * `run(): self`
 
 ## Methods:
@@ -117,9 +117,33 @@ Parameters:
 
 
 
+### `addFrontMatter(string $key, string $value): self`
+
+Add Jekyll front matter.
+
+
+Parameters:
+* `$key`: `string` Key  
+* `$value`: `string` Value  
+
+
+
+### `addIndexFrontMatter(string $key, string $value): self`
+
+Add Jekyll index front matter.
+
+
+Parameters:
+* `$key`: `string` Key  
+* `$value`: `string` Value  
+
+
+
 ### `run(): self`
 
 Run documentation builder.
 
 
 
+---
+Generated by [danog/phpdoc](https://phpdoc.daniil.it)

composer.json

@@ -4,22 +4,31 @@
     "type": "project",
     "license": "AGPL-3.0-only",
     "homepage": "https://phpdoc.daniil.it",
-    "keywords": ["phpdoc", "markdown", "documentation", "psalm"],
+    "keywords": [
+        "phpdoc",
+        "markdown",
+        "documentation",
+        "psalm"
+    ],
     "require": {
-        "php": ">=7.4.0",
+        "php": "^8.0",
         "danog/class-finder": "^0.4",
         "phpdocumentor/reflection-docblock": "^5.2",
+        "phpstan/phpdoc-parser": "^1.2",
         "symfony/yaml": "^6.0"
     },
     "require-dev": {
         "vimeo/psalm": "dev-master",
         "amphp/php-cs-fixer-config": "dev-master",
-        "friendsofphp/php-cs-fixer": "^2"
+        "friendsofphp/php-cs-fixer": "^2",
+        "phabel/phabel": "^1"
     },
-    "authors": [{
+    "authors": [
-        "name": "Daniil Gentili",
+        {
-        "email": "daniil@daniil.it"
+            "name": "Daniil Gentili",
-    }],
+            "email": "daniil@daniil.it"
+        }
+    ],
     "autoload": {
         "psr-4": {
             "danog\\PhpDoc\\": "src/"
@@ -29,13 +38,24 @@
         "bin/phpdoc"
     ],
     "scripts": {
-        "check": [
+        "build": [
-            "@cs",
+            "@cs-fix",
-            "@test"
+            "@phpdoc"
         ],
         "cs": "PHP_CS_FIXER_IGNORE_ENV=1 php-cs-fixer fix -v --diff --dry-run",
         "cs-fix": "PHP_CS_FIXER_IGNORE_ENV=1 php-cs-fixer fix -v --diff",
         "psalm": "psalm",
-        "docs": "php tools/build_docs.php"
+        "docs": "@phpdoc"
+    },
+    "config": {
+        "allow-plugins": {
+            "composer/package-versions-deprecated": true,
+            "phabel/phabel": true
+        }
+    },
+    "extra": {
+        "phabel": {
+            "revision": 0
+        }
     }
 }

src/PhpDoc.php

@@ -16,9 +16,12 @@
  * @link https://phpdoc.daniil.it PhpDoc documentation
  */
 
-namespace danog\PhpDoc\PhpDoc;
+namespace danog\PhpDoc;
 
 use danog\ClassFinder\ClassFinder;
+use danog\PhpDoc\PhpDoc\ClassDoc;
+use danog\PhpDoc\PhpDoc\FunctionDoc;
+use danog\PhpDoc\PhpDoc\GenericDoc;
 use phpDocumentor\Reflection\DocBlock\Tags\Author;
 use phpDocumentor\Reflection\DocBlockFactory;
 use ReflectionClass;
@@ -68,9 +71,17 @@ class PhpDoc
      */
     private string $description = 'PHPDOC documentation';
     /**
-     * Project image.
+     * Project front matter.
+     *
+     * @var array<string, string>
      */
-    private string $image = '';
+    private array $frontMatter = [];
+    /**
+     * Index front matter.
+     *
+     * @var array<string, string>
+     */
+    private array $indexFrontMatter = [];
     /**
      * Use map.
      *
@@ -244,14 +255,16 @@ class PhpDoc
         $description = \explode("\n", $this->description);
         $description = $description[0] ?? '';
 
-        $descriptionEscaped = Escaper::escapeWithDoubleQuotes($description);
+        $frontMatter = $this->getIndexFrontMatter(
-        $nameEscaped = Escaper::escapeWithDoubleQuotes($this->name);
+            [
+                'description' => $description,
+                'title' => $this->name,
+            ]
+        );
 
-        $image = $this->getImage();
         $index = <<<EOF
         ---
-        title: $nameEscaped
+        $frontMatter
-        description: $descriptionEscaped$image
         ---
         # `$this->name`
 
@@ -568,25 +581,62 @@ class PhpDoc
     }
 
     /**
-     * Get project image (front matter).
+     * Get front matter.
+     *
+     * @param array<string, string> $init Initial front matter
      *
      * @return string
      */
-    public function getImage(): string
+    public function getFrontMatter(array $init = []): string
     {
-        return $this->image ? "\nimage: ".$this->image : '';
+        $result = '';
+        foreach ($init + $this->frontMatter as $key => $value) {
+            $result .= "$key: ".Escaper::escapeWithDoubleQuotes($value)."\n";
+        }
+        return $result;
     }
 
     /**
-     * Set project image.
+     * Get index front matter.
      *
-     * @param string $image Project image
+     * @param array<string, string> $init Initial front matter
+     *
+     * @return string
+     */
+    private function getIndexFrontMatter(array $init = []): string
+    {
+        $result = '';
+        foreach ($init + $this->indexFrontMatter as $key => $value) {
+            $result .= "$key: ".Escaper::escapeWithDoubleQuotes($value)."\n";
+        }
+        return $result;
+    }
+
+    /**
+     * Add project front matter.
+     *
+     * @param string $key Key
+     * @param string $value Value
      *
      * @return self
      */
-    public function setImage(string $image): self
+    public function addFrontMatter(string $key, string $value): self
     {
-        $this->image = $image;
+        $this->frontMatter[$key] = $value;
+
+        return $this;
+    }
+    /**
+     * Add index front matter.
+     *
+     * @param string $key Key
+     * @param string $value Value
+     *
+     * @return self
+     */
+    public function addIndexFrontMatter(string $key, string $value): self
+    {
+        $this->indexFrontMatter[$key] = $value;
 
         return $this;
     }

src/PhpDoc/ClassDoc.php

@@ -2,6 +2,7 @@
 
 namespace danog\PhpDoc\PhpDoc;
 
+use danog\PhpDoc\PhpDoc;
 use phpDocumentor\Reflection\DocBlock\Tags\Generic;
 use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag;
 use phpDocumentor\Reflection\DocBlock\Tags\Property;

src/PhpDoc/FunctionDoc.php

@@ -2,6 +2,7 @@
 
 namespace danog\PhpDoc\PhpDoc;
 
+use danog\PhpDoc\PhpDoc;
 use ReflectionFunction;
 
 /**

src/PhpDoc/GenericDoc.php

@@ -2,6 +2,7 @@
 
 namespace danog\PhpDoc\PhpDoc;
 
+use danog\PhpDoc\PhpDoc;
 use phpDocumentor\Reflection\DocBlock;
 use phpDocumentor\Reflection\DocBlock\Description;
 use phpDocumentor\Reflection\DocBlock\Tags\Author;
@@ -13,7 +14,6 @@ use phpDocumentor\Reflection\DocBlock\Tags\See;
 use phpDocumentor\Reflection\Fqsen as ReflectionFqsen;
 use ReflectionClass;
 use ReflectionFunction;
-use Symfony\Component\Yaml\Escaper;
 
 /**
  * Generic documentation builder.
@@ -175,18 +175,19 @@ abstract class GenericDoc
             $authors .= "> Author: $author  \n";
         }
         $seeAlso = $this->seeAlso();
-        $image = $this->builder->getImage();
+        $frontMatter = $this->builder->getFrontMatter(
+            [
+                'title' => "{$this->name}: {$this->title}",
+                'description' => $this->description
+            ]
+        );
         $index = '';
         $count = \count(\explode('\\', $this->resolvedClassName)) - 2;
         $index .= \str_repeat('../', $count);
         $index .= 'index.md';
-        $titleEscaped = Escaper::escapeWithDoubleQuotes("{$this->name}: {$this->title}");
-        $descriptionEscaped = Escaper::escapeWithDoubleQuotes($this->description);
         return <<<EOF
         ---
-        title: $titleEscaped
+        $frontMatter
-        description: $descriptionEscaped
-        $image
         ---
         # `$this->name`
         [Back to index]($index)

src/PhpDoc/MethodDoc.php

@@ -2,6 +2,7 @@
 
 namespace danog\PhpDoc\PhpDoc;
 
+use danog\PhpDoc\PhpDoc;
 use phpDocumentor\Reflection\DocBlock\Description;
 use phpDocumentor\Reflection\DocBlock\Tags\Generic;
 use phpDocumentor\Reflection\DocBlock\Tags\Param;

src/PhpDocBuilder.php

@@ -18,7 +18,6 @@
 
 namespace danog\PhpDoc;
 
-use danog\PhpDoc\PhpDoc\PhpDoc;
 use phpDocumentor\Reflection\DocBlock\Tags\Author;
 
 /**
@@ -142,11 +141,38 @@ final class PhpDocBuilder
      */
     public function setImage(string $image): self
     {
-        $this->doc->setImage($image);
+        $this->doc->addFrontMatter('image', $image);
+        $this->doc->addIndexFrontMatter('image', $image);
 
         return $this;
     }
 
+    /**
+     * Add Jekyll front matter.
+     *
+     * @param string $key Key
+     * @param string $value Value
+     * @return self
+     */
+    public function addFrontMatter(string $key, string $value): self
+    {
+        $this->doc->addFrontMatter($key, $value);
+
+        return $this;
+    }
+    /**
+     * Add Jekyll index front matter.
+     *
+     * @param string $key Key
+     * @param string $value Value
+     * @return self
+     */
+    public function addIndexFrontMatter(string $key, string $value): self
+    {
+        $this->doc->addIndexFrontMatter($key, $value);
+
+        return $this;
+    }
     /**
      * Run documentation builder.
      *

src/index.md

@@ -0,0 +1,19 @@
+---
+description: "Simple markdown PHPDOC documentation generator with psalm type annotation support."
+title: "danog/phpdoc"
+
+---
+# `danog/phpdoc`
+
+Simple markdown PHPDOC documentation generator with psalm type annotation support.
+
+
+
+
+## Classes
+* [\danog\PhpDoc\PhpDocBuilder: PHP documentation builder.](danog/PhpDoc/PhpDocBuilder.md)
+
+
+
+---
+Generated by [danog/phpdoc](https://phpdoc.daniil.it).