Add comments

Author: adriansuter

src/CodeConverter.php

@@ -76,10 +76,10 @@ public function __construct(
         ?NodeFinder $nodeFinder = null
     ) {
         $this->lexer = $lexer ?? new Emulative(
-            [
+                [
                     'usedAttributes' => ['comments', 'startLine', 'endLine', 'startTokenPos', 'endTokenPos'],
                 ]
-        );
+            );
 
         $this->parser = $parser ?? new Php7($this->lexer);
 
@@ -111,10 +111,13 @@ public function convert(string $code, array $functionCallMap): string
         $overridePlaceholders = [];
 
         $newStmts = $this->traverser->traverse($oldStmts);
+
+        // Find function calls.
         $funcCalls = $this->nodeFinder->findInstanceOf($newStmts, FuncCall::class);
         foreach ($funcCalls as $funcCall) {
             /** @var FuncCall $funcCall */
             if (!$funcCall->name->hasAttribute(self::ATTR_RESOLVED_NAME)) {
+                // This function call has no resolved fully qualified name.
                 continue;
             }
 
@@ -123,18 +126,28 @@ public function convert(string $code, array $functionCallMap): string
 
             $resolvedNameCode = $resolvedName->toCodeString();
             if (isset($functionCallMap[$resolvedNameCode])) {
-                $k = uniqid(md5($resolvedNameCode), true);
-                $overridePlaceholders[$k] = $functionCallMap[$resolvedNameCode];
+                // There is a function call map > Create a unique key.
+                $key = uniqid(md5($resolvedNameCode), true);
+
+                // Put the key into the overridePlaceholders array as at the end we need to
+                // replace those keys with the corresponding target function call.
+                $overridePlaceholders[$key] = $functionCallMap[$resolvedNameCode];
 
-                $funcCall->name = new FullyQualified($k);
+                // Replace the name to be the fully qualified name, i.e. the given unique key
+                // (we will replace that at the end).
+                $funcCall->name = new FullyQualified($key);
             }
         }
 
+        // Print the source code.
         $code = $this->printer->printFormatPreserving($newStmts, $oldStmts, $oldTokens);
+
+        // Return the source code if there are no override placeholders.
         if (empty($overridePlaceholders)) {
             return $code;
         }
 
+        // Replace all override placeholders by their target function call.
         return str_replace(array_keys($overridePlaceholders), array_values($overridePlaceholders), $code);
     }
 }