Add classes and methods comments for API Documentation (#9)

* Add classes and methods comments for API Documentation

* Simplify phpunit.xml

* Ready to use Doctum

.gitignore

@@ -185,4 +185,6 @@ $RECYCLE.BIN/
 # Build data
 /build/
 
-# End of https://www.gitignore.io/api/git,macos,windows,composer,phpstorm,visualstudiocode
+# End of https://www.gitignore.io/api/git,macos,windows,composer,phpstorm,visualstudiocode
+/cache
+/doctum.php

composer.json

@@ -37,11 +37,10 @@
     "minimum-stability": "dev",
     "prefer-stable": true,
     "scripts": {
-        "test": [
-            "./vendor/bin/phpunit tests"
-        ],
-        "lint": [
-            "./vendor/bin/pint"
-        ]
+        "test": "./vendor/bin/phpunit tests",
+        "lint": "./vendor/bin/pint",
+        "inspect": "./vendor/bin/pint --test",
+        "api-doc": "doctum.phar update doctum.php --output-format=github --no-ansi --no-progress",
+        "api-parse": "doctum.phar parse doctum.php --output-format=github -v"
     }
 }

phpunit.xml.dist

@@ -1,23 +1,18 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.0/phpunit.xsd"
-         bootstrap="vendor/autoload.php"
-         cacheDirectory=".phpunit.cache"
-         executionOrder="depends,defects"
-         beStrictAboutCoverageMetadata="true"
-         beStrictAboutOutputDuringTests="true"
-         failOnRisky="true"
-         failOnWarning="true"
-         cacheResult ="false">
+    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+    bootstrap="vendor/autoload.php"
+    colors="true"
+    testdox="true">
     <testsuites>
         <testsuite name="default">
             <directory>tests</directory>
         </testsuite>
     </testsuites>
 
-    <source restrictDeprecations="true" restrictNotices="true" restrictWarnings="true">
+    <source>
         <include>
             <directory>src</directory>
         </include>
     </source>
-</phpunit>
+</phpunit>

src/Contracts/OptionParser.php

@@ -2,16 +2,19 @@
 
 namespace Cable8mm\GoodCodeParser\Contracts;
 
+/**
+ * OptionParser interface. Option Good must be implemented. This method is called when the parser recognizes option good.
+ */
 interface OptionParser
 {
     /**
-     * Undocumented function
+     * Find option-good code by parsing. Option-good can be matched by 'name', because option-good have not code.
      *
-     * @param  string  $code  before parsing
-     * @param  string  $name  good-name
+     * @param  string  $code  good code.
+     * @param  string  $name  good name.
      * @param  array  $goods  option-goods
      * @param  array  $options  option-good-options
-     * @return string|void code after parsing
+     * @return string|void Good code
      */
     public static function parse(string $code, string $name, array $goods, array $options);
 }

src/Contracts/Parser.php

@@ -2,15 +2,20 @@
 
 namespace Cable8mm\GoodCodeParser\Contracts;
 
+/**
+ * Parser interface.
+ *
+ * Various Good must be implemented. This method is called when the parser recognizes something like 'gift' or 'opt'.
+ */
 interface Parser
 {
     /**
-     * Parsing
+     * Find good code by parsing.
      *
      * @param  string  $goodCode  before parsing
-     * @return array|string after parsing
+     * @return array|string Good code
      *
-     * @throws Cable8mm\GoodCodeParser\Exception\MethodNotImplementedException
+     * @throws InvalidArgumentException
      */
-    public static function parse(string $parse, $goods = null);
+    public static function parse(string $parse, ?array $goods = null): array|string;
 }

src/GoodCodeParser.php

@@ -2,42 +2,50 @@
 
 namespace Cable8mm\GoodCodeParser;
 
+use Cable8mm\GoodCodeParser\Contracts\Parser;
+
+/**
+ * Good code can be parsed by the GoodCodeParser except option-good codes.
+ */
 class GoodCodeParser
 {
-    /**
-     * @var string Good code before parsing
-     */
+    /** @var string Good code before parsing */
     private $parse;
 
-    /**
-     * @var string|array Good code after parsing
-     */
+    /** @var string|array Good code after parsing */
     private $parsed;
 
+    /**
+     * Constructor.
+     *
+     * @param  string  $parse  Good code to be parsed.
+     *
+     * @example (new GoodCodeParser('set7369x4ZZ4235x6'))->with(SetGood::class)->get();
+     * @example (new GoodCodeParser('com2'))->with(ComplexGood::class, [1=>'set1x3ZZ43x2', 2=>...])->get();
+     * @example (new GoodCodeParser('gif1'))->with(ComplexGood::class, [1=>'set1x3ZZ43x2', 2=>...])->get();
+     */
     public function __construct(string $parse)
     {
         $this->parse = $parse;
     }
 
     /**
-     * @param string
-     * @return $this
+     * Ready to use a fit parser.
      *
-     * @var Cable8mm\GoodCodeParser\Contracts\Parser
+     * @param  $parser  The parser eg. SetGood::class, ComplexGood::class,...
+     * @param  array|null  $goods  The good codes
      */
-    public function with($parser, $goods = null)
+    public function with(string $parser, ?array $goods = null): static
     {
         $this->parsed = is_null($goods) ? $parser::parse($this->parse) : $parser::parse($this->parse, $goods);
 
         return $this;
     }
 
     /**
-     * Return code.
-     *
-     * @return array|string
+     * Return good code or good codes.
      */
-    public function get()
+    public function get(): array|string
     {
         return $this->parsed;
     }

src/OptionCodeParser.php

@@ -2,6 +2,11 @@
 
 namespace Cable8mm\GoodCodeParser;
 
+/**
+ * Option-good code can be parsed by the OptionGoodCodeParser.
+ *
+ * Option-good code can be matched by 'name', because option-good code have not code, so GoodCodeParser can not be used to parse option-good codes.
+ */
 class OptionCodeParser
 {
     /**
@@ -19,31 +24,36 @@ class OptionCodeParser
      */
     private $parsed;
 
+    /**
+     * Constructor.
+     *
+     * @param  string  $parse  Good name to be parsed.
+     * @param  string  $name  Option good name to be parsed.
+     */
     public function __construct(string $parse, string $name)
     {
         $this->parse = $parse;
         $this->name = $name;
     }
 
     /**
-     * @param string
-     * @return $this
+     * Ready to use a fit parser.
      *
-     * @var Cable8mm\GoodCodeParser\Contracts\OptionParser
+     * @param  string  $parser  Parser name eg. OptionGood::class.
+     * @param  array  $goods  Good code array
+     * @param  array  $options  Option code array
      */
-    public function with($parser, array $goods, array $options)
+    public function with(string $parser, array $goods, array $options): static
     {
         $this->parsed = $parser::parse($this->parse, $this->name, $goods, $options);
 
         return $this;
     }
 
     /**
-     * Return code.
-     *
-     * @return array|string
+     * Return option-good code or codes.
      */
-    public function get()
+    public function get(): array|string
     {
         return $this->parsed;
     }

src/Parsers/ComplexGood.php

@@ -11,11 +11,13 @@ final class ComplexGood implements Parser
 
     /**
      * {@inheritDoc}
+     *
+     * @throws InvalidArgumentException
      */
-    public static function parse(string $code, $goods = null)
+    public static function parse(string $code, ?array $goods = null): array|string
     {
         if (is_null($goods)) {
-            throw new InvalidArgumentException(__METHOD__);
+            throw new InvalidArgumentException('$goods must be an array');
         }
 
         $key = preg_replace('/^'.self::PREFIX.'/i', '', $code);

src/Parsers/GiftGood.php

@@ -11,7 +11,7 @@ final class GiftGood implements Parser
     /**
      * {@inheritDoc}
      */
-    public static function parse(string $code, $goods = null)
+    public static function parse(string $code, ?array $goods = null): array|string
     {
         $comCode = preg_replace('/^'.self::PREFIX.'/i', ComplexGood::PREFIX, $code);
 

src/Parsers/OptionGood.php

@@ -11,8 +11,10 @@ final class OptionGood implements OptionParser
 
     /**
      * {@inheritDoc}
+     *
+     * @throws InvalidArgumentException
      */
-    public static function parse(string $code, string $name, array $goods, array $options)
+    public static function parse(string $code, string $name, array $goods, array $options): array|string
     {
         $optionGood = null;
 

src/Parsers/SetGood.php

@@ -3,6 +3,7 @@
 namespace Cable8mm\GoodCodeParser\Parsers;
 
 use Cable8mm\GoodCodeParser\Contracts\Parser;
+use InvalidArgumentException;
 
 final class SetGood implements Parser
 {
@@ -13,25 +14,35 @@ final class SetGood implements Parser
     const DELIMITER_COUNT = 'x';
 
     /**
-     * {@inheritdoc}
+     * Find set-good code by parsing. A set of good code aka set-code is a combination of two more goods codes.
+     *
+     * @param  string  $goodCode  "set1232x3ZZ322ZZ4313x4" means "1232" x 3 + "322" x 4 + "4313" x 4. "1232", "322" and "4312" are good codes.
+     * @param  string  $goods  NEVER used.
+     * @return array|string Good code
+     *
+     * @throws InvalidArgumentException
      */
-    public static function parse(string $parse, $goods = null)
+    public static function parse(string $parse, $goods = null): array|string
     {
+        if (! is_null($goods)) {
+            throw new InvalidArgumentException('$goods is never used.');
+        }
+
         $escape = preg_replace('/^'.self::PREFIX.'/i', '', $parse);
 
         $goodCodes = explode(self::DELIMITER, $escape);
 
-        $parcedCodes = [];
+        $parsedCodes = [];
 
         foreach ($goodCodes as $code) {
             if (preg_match('/'.self::DELIMITER_COUNT.'/i', $code)) {
                 [$k, $v] = explode(self::DELIMITER_COUNT, $code);
             } else {
                 [$k, $v] = [$code, 1];
             }
-            $parcedCodes[$k] = $v;
+            $parsedCodes[$k] = $v;
         }
 
-        return $parcedCodes;
+        return $parsedCodes;
     }
 }