Improve type docs and variable naming

jfcherng · jfcherng · commit 2277a98481c5 · 2020-02-28T22:33:15.000+08:00
Signed-off-by: Jack Cherng &lt;jfcherng@gmail.com&gt;
diff --git a/src/Differ.php b/src/Differ.php
@@ -211,7 +211,7 @@ public static function getInstance(): self
      * matcher and performs the actual diff generation and return an array of the opcodes
      * for it. Once generated, the results are cached in the Differ class instance.
      *
-     * @return array[] array of the grouped opcodes for the generated diff
+     * @return int[][][] array of the grouped opcodes for the generated diff
      */
     public function getGroupedOpcodes(): array
     {
diff --git a/src/Renderer/AbstractRenderer.php b/src/Renderer/AbstractRenderer.php
@@ -161,7 +161,7 @@ abstract protected function renderWorker(Differ $differ): string;
     /**
      * The real worker for self::renderArray().
      *
-     * @param array $differArray the differ array
+     * @param array[][] $differArray the differ array
      */
     abstract protected function renderArrayWorker(array $differArray): string;
 
diff --git a/src/Renderer/Html/AbstractHtml.php b/src/Renderer/Html/AbstractHtml.php
@@ -49,7 +49,7 @@ public function getResultForIdenticalsDefault(): string
      *
      * @param Differ $differ the differ object
      *
-     * @return array generated changes, suitable for presentation in HTML
+     * @return array[][] generated changes, suitable for presentation in HTML
      */
     public function getChanges(Differ $differ): array
     {
@@ -62,14 +62,14 @@ public function getChanges(Differ $differ): array
         $old = $differ->getOld();
         $new = $differ->getNew();
 
-        $hunks = [];
+        $changes = [];
 
-        foreach ($differ->getGroupedOpcodes() as $opcodes) {
-            $hunk = [];
+        foreach ($differ->getGroupedOpcodes() as $hunk) {
+            $change = [];
             $lastOp = SequenceMatcher::OP_NOP;
             $lastBlock = 0;
 
-            foreach ($opcodes as [$op, $i1, $i2, $j1, $j2]) {
+            foreach ($hunk as [$op, $i1, $i2, $j1, $j2]) {
                 // if there are same amount of lines replaced
                 // we can render the inner detailed changes with corresponding lines
                 if ($op === SequenceMatcher::OP_REP && $i2 - $i1 === $j2 - $j1) {
@@ -79,8 +79,8 @@ public function getChanges(Differ $differ): array
                 }
 
                 if ($op !== $lastOp) {
-                    $hunk[] = $this->getDefaultBlock($op, $i1, $j1);
-                    $lastBlock = \count($hunk) - 1;
+                    $change[] = $this->getDefaultBlock($op, $i1, $j1);
+                    $lastBlock = \count($change) - 1;
                 }
 
                 $lastOp = $op;
@@ -90,9 +90,9 @@ public function getChanges(Differ $differ): array
                     // the old and the new may not be exactly the same
                     // because of ignoreCase, ignoreWhitespace, etc
                     $lines = \array_slice($old, $i1, $i2 - $i1);
-                    $hunk[$lastBlock]['old']['lines'] = $this->formatLines($lines);
+                    $change[$lastBlock]['old']['lines'] = $this->formatLines($lines);
                     $lines = \array_slice($new, $j1, $j2 - $j1);
-                    $hunk[$lastBlock]['new']['lines'] = $this->formatLines($lines);
+                    $change[$lastBlock]['new']['lines'] = $this->formatLines($lines);
 
                     continue;
                 }
@@ -106,7 +106,7 @@ public function getChanges(Differ $differ): array
                         $lines
                     );
 
-                    $hunk[$lastBlock]['old']['lines'] = $lines;
+                    $change[$lastBlock]['old']['lines'] = $lines;
                 }
 
                 if ($op & (SequenceMatcher::OP_REP | SequenceMatcher::OP_INS)) {
@@ -118,14 +118,14 @@ public function getChanges(Differ $differ): array
                         $lines
                     );
 
-                    $hunk[$lastBlock]['new']['lines'] = $lines;
+                    $change[$lastBlock]['new']['lines'] = $lines;
                 }
             }
 
-            $hunks[] = $hunk;
+            $changes[] = $change;
         }
 
-        return $hunks;
+        return $changes;
     }
 
     /**
@@ -149,7 +149,7 @@ protected function renderArrayWorker(array $differArray): string
     /**
      * Render the array of changes.
      *
-     * @param array $changes the changes
+     * @param array[][] $changes the changes
      *
      * @todo rename typo to renderChanges() in v7
      */
@@ -320,7 +320,7 @@ function (array $matches): string {
      *
      * Internally, we would like always int form for better performance.
      *
-     * @param array $changes the changes
+     * @param array[][] $changes the changes
      */
     protected function ensureChangesUseIntTag(array &$changes): void
     {
diff --git a/src/Renderer/Html/Inline.php b/src/Renderer/Html/Inline.php
@@ -82,7 +82,7 @@ protected function renderTableSeparateBlock(): string
     /**
      * Renderer table hunks.
      *
-     * @param array $hunks each hunk has many blocks
+     * @param array[][] $hunks each hunk has many blocks
      */
     protected function renderTableHunks(array $hunks): string
     {
diff --git a/src/Renderer/Html/Json.php b/src/Renderer/Html/Json.php
@@ -50,7 +50,7 @@ protected function redererChanges(array $changes): string
     /**
      * Convert tags of changes to their string form for better readability.
      *
-     * @param array $changes the changes
+     * @param array[][] $changes the changes
      */
     protected function convertTagToString(array &$changes): void
     {
diff --git a/src/Renderer/Html/LineRenderer/AbstractLineRenderer.php b/src/Renderer/Html/LineRenderer/AbstractLineRenderer.php
@@ -93,10 +93,10 @@ public function getRendererOptions(): array
     /**
      * Get the changed extent segments.
      *
-     * @param array $old the old array
-     * @param array $new the new array
+     * @param string[] $old the old array
+     * @param string[] $new the new array
      *
-     * @return array the changed extent segments
+     * @return int[][] the changed extent segments
      */
     protected function getChangedExtentSegments(array $old, array $new): array
     {
diff --git a/src/Renderer/Html/LineRenderer/Char.php b/src/Renderer/Html/LineRenderer/Char.php
@@ -18,10 +18,10 @@ final class Char extends AbstractLineRenderer
      */
     public function render(MbString $mbOld, MbString $mbNew): LineRendererInterface
     {
-        $opcodes = $this->getChangedExtentSegments($mbOld->toArray(), $mbNew->toArray());
+        $hunk = $this->getChangedExtentSegments($mbOld->toArray(), $mbNew->toArray());
 
-        // reversely iterate opcodes
-        foreach (ReverseIterator::fromArray($opcodes) as [$op, $i1, $i2, $j1, $j2]) {
+        // reversely iterate hunk
+        foreach (ReverseIterator::fromArray($hunk) as [$op, $i1, $i2, $j1, $j2]) {
             switch ($op) {
                 case SequenceMatcher::OP_DEL:
                     $mbOld->str_enclose_i(RendererConstant::HTML_CLOSURES, $i1, $i2 - $i1);
diff --git a/src/Renderer/Html/LineRenderer/Line.php b/src/Renderer/Html/LineRenderer/Line.php
@@ -45,7 +45,7 @@ public function render(MbString $mbOld, MbString $mbNew): LineRendererInterface
      * @param MbString $mbOld the old megabytes line
      * @param MbString $mbNew the new megabytes line
      *
-     * @return array Array containing the starting position (non-negative) and the ending position (negative)
+     * @return int[] Array containing the starting position (non-negative) and the ending position (negative)
      *               [0, 0] if two strings are the same
      */
     protected function getChangedExtentRegion(MbString $mbOld, MbString $mbNew): array
diff --git a/src/Renderer/Html/LineRenderer/Word.php b/src/Renderer/Html/LineRenderer/Word.php
@@ -23,10 +23,10 @@ public function render(MbString $mbOld, MbString $mbNew): LineRendererInterface
         $oldWords = $mbOld->toArraySplit($splitRegex, -1, \PREG_SPLIT_DELIM_CAPTURE);
         $newWords = $mbNew->toArraySplit($splitRegex, -1, \PREG_SPLIT_DELIM_CAPTURE);
 
-        $opcodes = $this->getChangedExtentSegments($oldWords, $newWords);
+        $hunk = $this->getChangedExtentSegments($oldWords, $newWords);
 
-        // reversely iterate opcodes
-        foreach (ReverseIterator::fromArray($opcodes) as [$op, $i1, $i2, $j1, $j2]) {
+        // reversely iterate hunk
+        foreach (ReverseIterator::fromArray($hunk) as [$op, $i1, $i2, $j1, $j2]) {
             switch ($op) {
                 case SequenceMatcher::OP_DEL:
                     $oldWords[$i1] = RendererConstant::HTML_CLOSURES[0] . $oldWords[$i1];
diff --git a/src/Renderer/Html/SideBySide.php b/src/Renderer/Html/SideBySide.php
@@ -74,7 +74,7 @@ protected function renderTableSeparateBlock(): string
     /**
      * Renderer table hunks.
      *
-     * @param array $hunks each hunk has many blocks
+     * @param array[][] $hunks each hunk has many blocks
      */
     protected function renderTableHunks(array $hunks): string
     {
diff --git a/src/Renderer/RendererConstant.php b/src/Renderer/RendererConstant.php
@@ -6,20 +6,39 @@
 
 final class RendererConstant
 {
+    /**
+     * The base namespace of renderers.
+     *
+     * @var string
+     */
     const RENDERER_NAMESPACE = __NAMESPACE__;
-    const RENDERER_TYPES = ['Html', 'Text'];
 
     /**
-     * Closures that are used to enclose partial strings.
+     * Available renderer types.
      *
-     * - a different part in string (class internal)
-     * - a inserted char in output HTML
-     * - a deleted char in output HTML
+     * @var string[]
+     */
+    const RENDERER_TYPES = ['Html', 'Text'];
+
+    /**
+     * Closures that are used to enclose different parts in string.
      *
      * @var string[]
      */
     const HTML_CLOSURES = ["\u{fcffc}\u{ff2fb}", "\u{fff41}\u{fcffc}"];
+
+    /**
+     * Closures that are used to enclose inserted chars in output HTML.
+     *
+     * @var string[]
+     */
     const HTML_CLOSURES_INS = ['<ins>', '</ins>'];
+
+    /**
+     * Closures that are used to enclose deleted chars in output HTML.
+     *
+     * @var string[]
+     */
     const HTML_CLOSURES_DEL = ['<del>', '</del>'];
 
     /**
diff --git a/src/Renderer/RendererInterface.php b/src/Renderer/RendererInterface.php
@@ -27,7 +27,7 @@ public function render(Differ $differ): string;
     /**
      * Render the differ array and return the result.
      *
-     * @param array $differArray the Differ array to be rendered
+     * @param array[][] $differArray the Differ array to be rendered
      *
      * @throws UnsupportedFunctionException if the renderer does not support this method
      */
diff --git a/src/Renderer/Text/Context.php b/src/Renderer/Text/Context.php
@@ -23,7 +23,7 @@ final class Context extends AbstractText
     ];
 
     /**
-     * @var array array of the different opcodes and their context diff equivalents
+     * @var string[] array of the different opcodes and their context diff equivalents
      */
     const TAG_MAP = [
         SequenceMatcher::OP_DEL => '-',
@@ -39,33 +39,33 @@ protected function renderWorker(Differ $differ): string
     {
         $ret = '';
 
-        foreach ($differ->getGroupedOpcodes() as $opcodes) {
-            $lastItem = \count($opcodes) - 1;
+        foreach ($differ->getGroupedOpcodes() as $hunk) {
+            $lastItem = \count($hunk) - 1;
 
-            $i1 = $opcodes[0][1];
-            $i2 = $opcodes[$lastItem][2];
-            $j1 = $opcodes[0][3];
-            $j2 = $opcodes[$lastItem][4];
+            $i1 = $hunk[0][1];
+            $i2 = $hunk[$lastItem][2];
+            $j1 = $hunk[0][3];
+            $j2 = $hunk[$lastItem][4];
 
             $ret .=
                 "***************\n" .
-                $this->renderBlockHeader('*', $i1, $i2) .
-                $this->renderBlockOld($opcodes, $differ) .
-                $this->renderBlockHeader('-', $j1, $j2) .
-                $this->renderBlockNew($opcodes, $differ);
+                $this->renderHunkHeader('*', $i1, $i2) .
+                $this->renderHunkOld($hunk, $differ) .
+                $this->renderHunkHeader('-', $j1, $j2) .
+                $this->renderHunkNew($hunk, $differ);
         }
 
         return $ret;
     }
 
     /**
-     * Render the block header.
+     * Render the hunk header.
      *
      * @param string $delimiter the delimiter
      * @param int    $a1        the a1
      * @param int    $a2        the a2
      */
-    protected function renderBlockHeader(string $delimiter, int $a1, int $a2): string
+    protected function renderHunkHeader(string $delimiter, int $a1, int $a2): string
     {
         return
             "{$delimiter}{$delimiter}{$delimiter} " .
@@ -74,48 +74,42 @@ protected function renderBlockHeader(string $delimiter, int $a1, int $a2): strin
     }
 
     /**
-     * Render the old block.
+     * Render the old hunk.
      *
-     * @param array  $opcodes the opcodes
-     * @param Differ $differ  the differ object
+     * @param int[][] $hunk   the hunk
+     * @param Differ  $differ the differ object
      */
-    protected function renderBlockOld(array $opcodes, Differ $differ): string
+    protected function renderHunkOld(array $hunk, Differ $differ): string
     {
         $ret = '';
 
-        foreach ($opcodes as [$op, $i1, $i2, $j1, $j2]) {
+        foreach ($hunk as [$op, $i1, $i2, $j1, $j2]) {
             if ($op === SequenceMatcher::OP_INS) {
                 continue;
             }
 
-            $ret .= $this->renderContext(
-                self::TAG_MAP[$op],
-                $differ->getOld($i1, $i2)
-            );
+            $ret .= $this->renderContext(self::TAG_MAP[$op], $differ->getOld($i1, $i2));
         }
 
         return $ret;
     }
 
     /**
-     * Render the new block.
+     * Render the new hunk.
      *
-     * @param array  $opcodes the opcodes
-     * @param Differ $differ  the differ object
+     * @param int[][] $hunk   the hunk
+     * @param Differ  $differ the differ object
      */
-    protected function renderBlockNew(array $opcodes, Differ $differ): string
+    protected function renderHunkNew(array $hunk, Differ $differ): string
     {
         $ret = '';
 
-        foreach ($opcodes as [$op, $i1, $i2, $j1, $j2]) {
+        foreach ($hunk as [$op, $i1, $i2, $j1, $j2]) {
             if ($op === SequenceMatcher::OP_DEL) {
                 continue;
             }
 
-            $ret .= $this->renderContext(
-                self::TAG_MAP[$op],
-                $differ->getNew($j1, $j2)
-            );
+            $ret .= $this->renderContext(self::TAG_MAP[$op], $differ->getNew($j1, $j2));
         }
 
         return $ret;
@@ -124,8 +118,8 @@ protected function renderBlockNew(array $opcodes, Differ $differ): string
     /**
      * Render the context array with the symbol.
      *
-     * @param string $symbol  the leading symbol
-     * @param array  $context the context
+     * @param string   $symbol  the leading symbol
+     * @param string[] $context the context
      */
     protected function renderContext(string $symbol, array $context): string
     {
diff --git a/src/Renderer/Text/Unified.php b/src/Renderer/Text/Unified.php

Original file line number	Diff line number	Diff line change
`@@ -211,7 +211,7 @@ public static function getInstance(): self`
`211`	`211`	`* matcher and performs the actual diff generation and return an array of the opcodes`
`212`	`212`	`* for it. Once generated, the results are cached in the Differ class instance.`
`213`	`213`	`*`
`214`		`- * @return array[] array of the grouped opcodes for the generated diff`
	`214`	`+ * @return int[][][] array of the grouped opcodes for the generated diff`
`215`	`215`	`*/`
`216`	`216`	`public function getGroupedOpcodes(): array`
`217`	`217`	`{`
Original file line number	Diff line number	Diff line change
`@@ -161,7 +161,7 @@ abstract protected function renderWorker(Differ $differ): string;`
`161`	`161`	`/**`
`162`	`162`	`* The real worker for self::renderArray().`
`163`	`163`	`*`
`164`		`- * @param array $differArray the differ array`
	`164`	`+ * @param array[][] $differArray the differ array`
`165`	`165`	`*/`
`166`	`166`	`abstract protected function renderArrayWorker(array $differArray): string;`
`167`	`167`
Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,7 @@ public function getResultForIdenticalsDefault(): string`
`49`	`49`	`*`
`50`	`50`	`* @param Differ $differ the differ object`
`51`	`51`	`*`
`52`		`- * @return array generated changes, suitable for presentation in HTML`
	`52`	`+ * @return array[][] generated changes, suitable for presentation in HTML`
`53`	`53`	`*/`
`54`	`54`	`public function getChanges(Differ $differ): array`
`55`	`55`	`{`
`@@ -62,14 +62,14 @@ public function getChanges(Differ $differ): array`
`62`	`62`	`$old = $differ->getOld();`
`63`	`63`	`$new = $differ->getNew();`
`64`	`64`
`65`		`- $hunks = [];`
	`65`	`+ $changes = [];`
`66`	`66`
`67`		`- foreach ($differ->getGroupedOpcodes() as $opcodes) {`
`68`		`- $hunk = [];`
	`67`	`+ foreach ($differ->getGroupedOpcodes() as $hunk) {`
	`68`	`+ $change = [];`
`69`	`69`	`$lastOp = SequenceMatcher::OP_NOP;`
`70`	`70`	`$lastBlock = 0;`
`71`	`71`
`72`		`- foreach ($opcodes as [$op, $i1, $i2, $j1, $j2]) {`
	`72`	`+ foreach ($hunk as [$op, $i1, $i2, $j1, $j2]) {`
`73`	`73`	`// if there are same amount of lines replaced`
`74`	`74`	`// we can render the inner detailed changes with corresponding lines`
`75`	`75`	`if ($op === SequenceMatcher::OP_REP && $i2 - $i1 === $j2 - $j1) {`
`@@ -79,8 +79,8 @@ public function getChanges(Differ $differ): array`
`79`	`79`	`}`
`80`	`80`
`81`	`81`	`if ($op !== $lastOp) {`
`82`		`- $hunk[] = $this->getDefaultBlock($op, $i1, $j1);`
`83`		`- $lastBlock = \count($hunk) - 1;`
	`82`	`+ $change[] = $this->getDefaultBlock($op, $i1, $j1);`
	`83`	`+ $lastBlock = \count($change) - 1;`
`84`	`84`	`}`
`85`	`85`
`86`	`86`	`$lastOp = $op;`
`@@ -90,9 +90,9 @@ public function getChanges(Differ $differ): array`
`90`	`90`	`// the old and the new may not be exactly the same`
`91`	`91`	`// because of ignoreCase, ignoreWhitespace, etc`
`92`	`92`	`$lines = \array_slice($old, $i1, $i2 - $i1);`
`93`		`- $hunk[$lastBlock]['old']['lines'] = $this->formatLines($lines);`
	`93`	`+ $change[$lastBlock]['old']['lines'] = $this->formatLines($lines);`
`94`	`94`	`$lines = \array_slice($new, $j1, $j2 - $j1);`
`95`		`- $hunk[$lastBlock]['new']['lines'] = $this->formatLines($lines);`
	`95`	`+ $change[$lastBlock]['new']['lines'] = $this->formatLines($lines);`
`96`	`96`
`97`	`97`	`continue;`
`98`	`98`	`}`
`@@ -106,7 +106,7 @@ public function getChanges(Differ $differ): array`
`106`	`106`	`$lines`
`107`	`107`	`);`
`108`	`108`
`109`		`- $hunk[$lastBlock]['old']['lines'] = $lines;`
	`109`	`+ $change[$lastBlock]['old']['lines'] = $lines;`
`110`	`110`	`}`
`111`	`111`
`112`	`112`	`if ($op & (SequenceMatcher::OP_REP \| SequenceMatcher::OP_INS)) {`
`@@ -118,14 +118,14 @@ public function getChanges(Differ $differ): array`
`118`	`118`	`$lines`
`119`	`119`	`);`
`120`	`120`
`121`		`- $hunk[$lastBlock]['new']['lines'] = $lines;`
	`121`	`+ $change[$lastBlock]['new']['lines'] = $lines;`
`122`	`122`	`}`
`123`	`123`	`}`
`124`	`124`
`125`		`- $hunks[] = $hunk;`
	`125`	`+ $changes[] = $change;`
`126`	`126`	`}`
`127`	`127`
`128`		`- return $hunks;`
	`128`	`+ return $changes;`
`129`	`129`	`}`
`130`	`130`
`131`	`131`	`/**`
`@@ -149,7 +149,7 @@ protected function renderArrayWorker(array $differArray): string`
`149`	`149`	`/**`
`150`	`150`	`* Render the array of changes.`
`151`	`151`	`*`
`152`		`- * @param array $changes the changes`
	`152`	`+ * @param array[][] $changes the changes`
`153`	`153`	`*`
`154`	`154`	`* @todo rename typo to renderChanges() in v7`
`155`	`155`	`*/`
`@@ -320,7 +320,7 @@ function (array $matches): string {`
`320`	`320`	`*`
`321`	`321`	`* Internally, we would like always int form for better performance.`
`322`	`322`	`*`
`323`		`- * @param array $changes the changes`
	`323`	`+ * @param array[][] $changes the changes`
`324`	`324`	`*/`
`325`	`325`	`protected function ensureChangesUseIntTag(array &$changes): void`
`326`	`326`	`{`
Original file line number	Diff line number	Diff line change
`@@ -82,7 +82,7 @@ protected function renderTableSeparateBlock(): string`
`82`	`82`	`/**`
`83`	`83`	`* Renderer table hunks.`
`84`	`84`	`*`
`85`		`- * @param array $hunks each hunk has many blocks`
	`85`	`+ * @param array[][] $hunks each hunk has many blocks`
`86`	`86`	`*/`
`87`	`87`	`protected function renderTableHunks(array $hunks): string`
`88`	`88`	`{`
Original file line number	Diff line number	Diff line change
`@@ -50,7 +50,7 @@ protected function redererChanges(array $changes): string`
`50`	`50`	`/**`
`51`	`51`	`* Convert tags of changes to their string form for better readability.`
`52`	`52`	`*`
`53`		`- * @param array $changes the changes`
	`53`	`+ * @param array[][] $changes the changes`
`54`	`54`	`*/`
`55`	`55`	`protected function convertTagToString(array &$changes): void`
`56`	`56`	`{`
Original file line number	Diff line number	Diff line change
`@@ -93,10 +93,10 @@ public function getRendererOptions(): array`
`93`	`93`	`/**`
`94`	`94`	`* Get the changed extent segments.`
`95`	`95`	`*`
`96`		`- * @param array $old the old array`
`97`		`- * @param array $new the new array`
	`96`	`+ * @param string[] $old the old array`
	`97`	`+ * @param string[] $new the new array`
`98`	`98`	`*`
`99`		`- * @return array the changed extent segments`
	`99`	`+ * @return int[][] the changed extent segments`
`100`	`100`	`*/`
`101`	`101`	`protected function getChangedExtentSegments(array $old, array $new): array`
`102`	`102`	`{`
Original file line number	Diff line number	Diff line change
`@@ -45,7 +45,7 @@ public function render(MbString $mbOld, MbString $mbNew): LineRendererInterface`
`45`	`45`	`* @param MbString $mbOld the old megabytes line`
`46`	`46`	`* @param MbString $mbNew the new megabytes line`
`47`	`47`	`*`
`48`		`- * @return array Array containing the starting position (non-negative) and the ending position (negative)`
	`48`	`+ * @return int[] Array containing the starting position (non-negative) and the ending position (negative)`
`49`	`49`	`* [0, 0] if two strings are the same`
`50`	`50`	`*/`
`51`	`51`	`protected function getChangedExtentRegion(MbString $mbOld, MbString $mbNew): array`
Original file line number	Diff line number	Diff line change
`@@ -74,7 +74,7 @@ protected function renderTableSeparateBlock(): string`
`74`	`74`	`/**`
`75`	`75`	`* Renderer table hunks.`
`76`	`76`	`*`
`77`		`- * @param array $hunks each hunk has many blocks`
	`77`	`+ * @param array[][] $hunks each hunk has many blocks`
`78`	`78`	`*/`
`79`	`79`	`protected function renderTableHunks(array $hunks): string`
`80`	`80`	`{`