Merge pull request #6 from jolicode/feat/document-generated

chore(doc): document all ast code by explaining what it generates
jolicode · Sep 28, 2023 · 418fd7b · 418fd7b
2 parents 24e0a8b + 264f637
commit 418fd7b
Show file tree

Hide file tree

Showing 22 changed files with 459 additions and 15 deletions.
diff --git a/src/Extractor/ReadAccessor.php b/src/Extractor/ReadAccessor.php
@@ -53,11 +53,11 @@ public function getExpression(Expr\Variable $input): Expr
 
                 foreach ($parameters as $parameter) {
                     if ($attribute = ($parameter->getAttributes(MapToContext::class)[0] ?? null)) {
-                        // generates code similar to:
-                        // $value->getValue(
-                        //     $context['map_to_accessor_parameter']['some_key'] ?? throw new \InvalidArgumentException('error message');
-                        // )
-
+                        /*
+                         * Create method call argument to read value from context and throw exception if not found
+                         *
+                         * $context['map_to_accessor_parameter']['some_key'] ?? throw new \InvalidArgumentException('error message');
+                         */
                         $methodCallArguments[] = new Arg(
                             new Expr\BinaryOp\Coalesce(
                                 new Expr\ArrayDimFetch(
@@ -88,6 +88,13 @@ public function getExpression(Expr\Variable $input): Expr
             }
 
             if ($this->private) {
+                /*
+                 * When the method is private we use the extract callback that can read this value
+                 *
+                 * @see \AutoMapper\Extractor\ReadAccessor::getExtractCallback()
+                 *
+                 * $this->extractCallbacks['method_name']($input)
+                 */
                 return new Expr\FuncCall(
                     new Expr\ArrayDimFetch(new Expr\PropertyFetch(new Expr\Variable('this'), 'extractCallbacks'), new Scalar\String_($this->name ?? $this->accessor)),
                     [
@@ -96,11 +103,23 @@ public function getExpression(Expr\Variable $input): Expr
                 );
             }
 
+            /*
+             * Use the method call to read the value
+             *
+             * $input->method_name(...$args)
+             */
             return new Expr\MethodCall($input, $this->accessor, $methodCallArguments);
         }
 
         if (self::TYPE_PROPERTY === $this->type) {
             if ($this->private) {
+                /*
+                 * When the property is private we use the extract callback that can read this value
+                 *
+                 * @see \AutoMapper\Extractor\ReadAccessor::getExtractCallback()
+                 *
+                 * $this->extractCallbacks['property_name']($input)
+                 */
                 return new Expr\FuncCall(
                     new Expr\ArrayDimFetch(new Expr\PropertyFetch(new Expr\Variable('this'), 'extractCallbacks'), new Scalar\String_($this->accessor)),
                     [
@@ -109,10 +128,20 @@ public function getExpression(Expr\Variable $input): Expr
                 );
             }
 
+            /*
+             * Use the property fetch to read the value
+             *
+             * $input->property_name
+             */
             return new Expr\PropertyFetch($input, $this->accessor);
         }
 
         if (self::TYPE_ARRAY_DIMENSION === $this->type) {
+            /*
+             * Use the array dim fetch to read the value
+             *
+             * $input['property_name']
+             */
             return new Expr\ArrayDimFetch($input, new Scalar\String_($this->accessor));
         }
 
@@ -132,6 +161,17 @@ public function getExtractCallback(string $className): ?Expr
             return null;
         }
 
+        /*
+         * Create extract callback for this accessor
+         *
+         *  \Closure::bind(function ($object) {
+         *      return $object->property_name;
+         *  }, null, $className)
+         *
+         *  \Closure::bind(function ($object) {
+         *      return $object->method_name();
+         *  }, null, $className)
+         */
         return new Expr\StaticCall(new Name\FullyQualified(\Closure::class), 'bind', [
             new Arg(
                 new Expr\Closure([

diff --git a/src/Extractor/WriteMutator.php b/src/Extractor/WriteMutator.php
@@ -41,13 +41,23 @@ public function __construct(
     public function getExpression(Expr\Variable $output, Expr $value, bool $byRef = false): ?Expr
     {
         if (self::TYPE_METHOD === $this->type || self::TYPE_ADDER_AND_REMOVER === $this->type) {
+            /*
+             * Create method call expression to write value
+             *
+             * $output->method($value);
+             */
             return new Expr\MethodCall($output, $this->name, [
                 new Arg($value),
             ]);
         }
 
         if (self::TYPE_PROPERTY === $this->type) {
             if ($this->private) {
+                /*
+                 * Use hydrate callback to write value
+                 *
+                 * $this->hydrateCallbacks['propertyName']($output, $value);
+                 */
                 return new Expr\FuncCall(
                     new Expr\ArrayDimFetch(new Expr\PropertyFetch(new Expr\Variable('this'), 'hydrateCallbacks'), new Scalar\String_($this->name)),
                     [
@@ -56,6 +66,12 @@ public function getExpression(Expr\Variable $output, Expr $value, bool $byRef =
                     ]
                 );
             }
+
+            /*
+             * Create property expression to write value
+             *
+             * $output->propertyName &= $value;
+             */
             if ($byRef) {
                 return new Expr\AssignRef(new Expr\PropertyFetch($output, $this->name), $value);
             }
@@ -64,6 +80,11 @@ public function getExpression(Expr\Variable $output, Expr $value, bool $byRef =
         }
 
         if (self::TYPE_ARRAY_DIMENSION === $this->type) {
+            /*
+             * Create array write expression to write value
+             *
+             * $output['propertyName'] &= $value;
+             */
             if ($byRef) {
                 return new Expr\AssignRef(new Expr\ArrayDimFetch($output, new Scalar\String_($this->name)), $value);
             }
@@ -83,6 +104,13 @@ public function getHydrateCallback(string $className): ?Expr
             return null;
         }
 
+        /*
+         * Create hydrate callback for this mutator
+         *
+         * \Closure::bind(function ($object, $value) {
+         *    $object->propertyName = $value;
+         * }, null, $className)
+         */
         return new Expr\StaticCall(new Name\FullyQualified(\Closure::class), 'bind', [
             new Arg(new Expr\Closure([
                 'params' => [