Merge branch 'origin/QA_5_3' into main

williamdes · williamdes · commit 9cbfd659db17 · 2021-04-21T19:05:48.000+02:00
diff --git a/.gitattributes b/.gitattributes
@@ -2,8 +2,15 @@
 .gitignore export-ignore
 .github export-ignore
 phpcs.xml.dist export-ignore
+phpunit.xml.dist export-ignore
 phpstan.neon.dist export-ignore
 phpstan-baseline.neon export-ignore
 scripts export-ignore
-makefile export-ignore
+Makefile export-ignore
 src/Resources/themes/default/data export-ignore
+.editorconfig export-ignore
+/examples export-ignore
+/locale/Doctum.pot export-ignore
+/locale/*.po export-ignore
+/tests export-ignore
+CHANGELOG.md export-ignore
diff --git a/composer.json b/composer.json
@@ -61,7 +61,11 @@
     },
     "autoload": {
         "psr-4": {
-            "Doctum\\": "src/",
+            "Doctum\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
             "Doctum\\Tests\\": "tests/"
         }
     },
diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon
@@ -1900,11 +1900,6 @@ parameters:
 			count: 1
 			path: src/Renderer/TwigExtension.php
 
-		-
-			message: "#^Method Doctum\\\\Renderer\\\\TwigExtension\\:\\:parseDesc\\(\\) has parameter \\$desc with no typehint specified\\.$#"
-			count: 1
-			path: src/Renderer/TwigExtension.php
-
 		-
 			message: "#^Method Doctum\\\\Renderer\\\\TwigExtension\\:\\:pathForClass\\(\\) has parameter \\$context with no value type specified in iterable type array\\.$#"
 			count: 1
diff --git a/src/Renderer/TwigExtension.php b/src/Renderer/TwigExtension.php
@@ -140,16 +140,18 @@ public static function abbrClass($class, bool $absolute = false): string
         return sprintf('<abbr title="%s">%s</abbr>', htmlentities($class, ENT_QUOTES), htmlspecialchars($short));
     }
 
-    public function parseDesc(array $context, $desc, Reflection $classOrFunctionRefl)
+    public function parseDesc(array $context, ?string $desc, Reflection $classOrFunctionRefl)
     {
-        if (!$desc) {
+        if ($desc === null || $desc === '') {
             return $desc;
         }
 
         if (null === $this->markdown) {
             $this->markdown = new Parsedown();
         }
 
+        $desc = str_replace(['<code>', '</code>'], ['```', '```'], $desc);
+
         // FIXME: the @see argument is more complex than just a class (Class::Method, local method directly, ...)
         $desc = preg_replace_callback(
             '/@see ([^ ]+)/',
diff --git a/src/Resources/themes/default/class.twig b/src/Resources/themes/default/class.twig
@@ -246,7 +246,7 @@
                 <div class="col-md-2 type">
                     {% if method.static %}static&nbsp;{% endif %}{{ hint_link(method.hint) }}
                 </div>
-                <div class="col-md-8 type">
+                <div class="col-md-8">
                     <a href="#method_{{ method.name|raw }}">{{ method.name|raw }}</a>{{ block('method_parameters_signature') }}
                     {% if not method.shortdesc %}
                         <p class="no-description">{% trans 'No description' %}</p>
diff --git a/src/Resources/themes/default/css/doctum.css b/src/Resources/themes/default/css/doctum.css
@@ -336,6 +336,10 @@ a abbr {
     font-size: 90%;
 }
 
+.type {
+    overflow-wrap: break-word;
+}
+
 /* Namespaces page */
 
 .namespaces {
@@ -352,6 +356,13 @@ a abbr {
     margin: 0 0 20px 0;
 }
 
+.namespace-container > h2 {
+    background-color: #edf3fe;
+    padding: 4px 4px 4px 8px;
+    font-size: 25px;
+    margin: 20px 0;
+}
+
 @media (max-width: 991px) {
     .namespaces .namespace-container {
         margin-right: 0;
@@ -390,13 +401,15 @@ pre {
 pre.examples {
     padding: 1rem;
 }
-h2 {
+
+#page-content > h2 {
     background-color: #edf3fe;
     padding: 4px 4px 4px 8px;
     font-size: 25px;
     margin: 20px 0;
 }
 
+
 /** Doc index **/
 
 dt {
@@ -432,14 +445,14 @@ dd {
     border-bottom: 1px solid #ccc;
 }
 
-.search-results h2 {
+.search-results > li > h2 {
     background: none;
     margin: 0;
     padding: 0;
     font-size: 18px;
 }
 
-.search-results h2 a {
+.search-results  > li > h2 > a {
     float: left;
     display: block;
     margin: 0 0 4px 0;
diff --git a/src/Resources/themes/default/namespace.twig b/src/Resources/themes/default/namespace.twig
@@ -48,7 +48,7 @@
                         {% if function.isPrivate() %}private{% endif %}
                         {{ hint_link(function.hint) }}
                     </div>
-                    <div class="col-md-8 type">
+                    <div class="col-md-8">
                         {{ function.name|raw }}
                         {{- function_parameters_signature(function) -}}
                         <br>
diff --git a/tests/Console/CommandHelpTest.php b/tests/Console/CommandHelpTest.php
@@ -2,7 +2,7 @@
 
 declare(strict_types = 1);
 
-namespace Doctum\Tests\Command;
+namespace Doctum\Tests\Console;
 
 use Doctum\Console\Command\ParseCommand;
 use Doctum\Console\Command\RenderCommand;
diff --git a/tests/Console/CommandTest.php b/tests/Console/CommandTest.php
@@ -2,7 +2,7 @@
 
 declare(strict_types = 1);
 
-namespace Doctum\Tests\Command;
+namespace Doctum\Tests\Console;
 
 use Doctum\Console\Command\ParseCommand;
 use Doctum\Console\Command\RenderCommand;
diff --git a/tests/Renderer/DiffTest.php b/tests/Renderer/DiffTest.php
@@ -7,7 +7,7 @@
 use Doctum\Renderer\Diff;
 use Doctum\Tests\AbstractTestCase;
 
-class RendererTest extends AbstractTestCase
+class DiffTest extends AbstractTestCase
 {
 
     public function testIsPhpClass(): void
diff --git a/tests/Renderer/TwigExtensionTest.php b/tests/Renderer/TwigExtensionTest.php
@@ -80,7 +80,81 @@ public function dataProviderParseDesc(): array
                     . '<p>' . "\n"
                     . 'Emulated prepared statements does not communicate with the database server' . "\n"
                     . 'so <b>PDO::prepare</b> does not check the statement.'
-            ]
+            ],
+            [
+                'Collects rows for insert into a database until the buffer size is reached.' . "\n"
+                . ' Then flushes the buffer to the database and starts over again.' . "\n"
+                . '' . "\n"
+                . ' Benefits over collecting a (possibly huge) insert array and then using' . "\n"
+                . ' $db->sql_multi_insert() include:' . "\n"
+                . '' . "\n"
+                . '  - Going over max packet size of the database connection is usually prevented' . "\n"
+                . '    because the data is submitted in batches.' . "\n"
+                . '' . "\n"
+                . '  - Reaching database connection timeout is usually prevented because' . "\n"
+                . '    submission of batches talks to the database every now and then.' . "\n"
+                . '' . "\n"
+                . '  - Usage of less PHP memory because data no longer needed is discarded on' . "\n"
+                . '    buffer flush.' . "\n"
+                . '' . "\n"
+                . ' Attention:' . "\n"
+                . ' Please note that users of this class have to call flush() to flush the' . "\n"
+                . ' remaining rows to the database after their batch insert operation is' . "\n"
+                . ' finished.' . "\n"
+                . '' . "\n"
+                . ' Usage:' . "\n"
+                . ' <code>' . "\n"
+                . '	$buffer = new \phpbb\db\sql_insert_buffer($db, \'test_table\', 1234);' . "\n"
+                . '' . "\n"
+                . '	while (do_stuff())' . "\n"
+                . '	{' . "\n"
+                . '		$buffer->insert(array(' . "\n"
+                . '			\'column1\' => \'value1\',' . "\n"
+                . '			\'column2\' => \'value2\',' . "\n"
+                . '		));' . "\n"
+                . '	}' . "\n"
+                . '' . "\n"
+                . '	$buffer->flush();' . "\n"
+                . ' </code>' . "\n",
+                '<p>Collects rows for insert into a database until the buffer size is reached.' . "\n"
+                . 'Then flushes the buffer to the database and starts over again.</p>' . "\n"
+                . ''
+                . '<p>Benefits over collecting a (possibly huge) insert array and then using' . "\n"
+                . '$db-&gt;sql_multi_insert() include:</p>' . "\n"
+                . '<ul>' . "\n"
+                . '<li>' . "\n"
+                . '<p>Going over max packet size of the database connection is usually prevented' . "\n"
+                . 'because the data is submitted in batches.</p>' . "\n"
+                . '</li>' . "\n"
+                . '<li>' . "\n"
+                . '<p>Reaching database connection timeout is usually prevented because' . "\n"
+                . 'submission of batches talks to the database every now and then.</p>' . "\n"
+                . '</li>' . "\n"
+                . '<li>' . "\n"
+                . '<p>Usage of less PHP memory because data no longer needed is discarded on' . "\n"
+                . 'buffer flush.</p>' . "\n"
+                . ''
+                . '<p>Attention:' . "\n"
+                . 'Please note that users of this class have to call flush() to flush the' . "\n"
+                . 'remaining rows to the database after their batch insert operation is' . "\n"
+                . 'finished.</p>' . "\n"
+                . ''
+                . '<p>Usage:</p>' . "\n"
+                . '<pre><code>'
+                . '$buffer = new \phpbb\db\sql_insert_buffer($db, \'test_table\', 1234);' . "\n"
+                . '' . "\n"
+                . 'while (do_stuff())' . "\n"
+                . '{' . "\n"
+                . '    $buffer-&gt;insert(array(' . "\n"
+                . '        \'column1\' =&gt; \'value1\',' . "\n"
+                . '        \'column2\' =&gt; \'value2\',' . "\n"
+                . '    ));' . "\n"
+                . '}' . "\n"
+                . '' . "\n"
+                . '$buffer-&gt;flush();</code></pre>' . "\n"
+                . '</li>' . "\n"
+                . '</ul>'
+            ],
         ];
     }
 
diff --git a/tests/phar/data/absolute_1.out b/tests/phar/data/absolute_1.out
@@ -4,18 +4,18 @@ Version main
 ------------
 
 
-Parsing Foo\Foo total: 64 errors
-Parsing Models\LaravelModel total: 64 errors
-Parsing IPv4Address total: 64 errors
-Parsing MyContainer total: 65 errors
-Parsing Collection total: 65 errors
-Parsing DogCollection total: 65 errors
-Parsing PersistentCollection total: 65 errors
-Parsing Cat total: 65 errors
-Parsing Foo total: 65 errors
-Parsing Bar total: 65 errors
-Parsing SuperCoolLibrary\Meta total: 65 errors
-Parsing Net_Sample total: 65 errors
+Parsing Foo\Foo total: 62 errors
+Parsing Models\LaravelModel total: 62 errors
+Parsing IPv4Address total: 62 errors
+Parsing MyContainer total: 63 errors
+Parsing Collection total: 63 errors
+Parsing DogCollection total: 63 errors
+Parsing PersistentCollection total: 63 errors
+Parsing Cat total: 63 errors
+Parsing Foo total: 63 errors
+Parsing Bar total: 63 errors
+Parsing SuperCoolLibrary\Meta total: 63 errors
+Parsing Net_Sample total: 63 errors
 Parsing done
 
 Rendering Global index.html
diff --git a/tests/phar/data/relative_1.out b/tests/phar/data/relative_1.out
@@ -4,18 +4,18 @@ Version main
 ------------
 
 
-Parsing Foo\Foo total: 64 errors
-Parsing Models\LaravelModel total: 64 errors
-Parsing IPv4Address total: 64 errors
-Parsing MyContainer total: 65 errors
-Parsing Collection total: 65 errors
-Parsing DogCollection total: 65 errors
-Parsing PersistentCollection total: 65 errors
-Parsing Cat total: 65 errors
-Parsing Foo total: 65 errors
-Parsing Bar total: 65 errors
-Parsing SuperCoolLibrary\Meta total: 65 errors
-Parsing Net_Sample total: 65 errors
+Parsing Foo\Foo total: 62 errors
+Parsing Models\LaravelModel total: 62 errors
+Parsing IPv4Address total: 62 errors
+Parsing MyContainer total: 63 errors
+Parsing Collection total: 63 errors
+Parsing DogCollection total: 63 errors
+Parsing PersistentCollection total: 63 errors
+Parsing Cat total: 63 errors
+Parsing Foo total: 63 errors
+Parsing Bar total: 63 errors
+Parsing SuperCoolLibrary\Meta total: 63 errors
+Parsing Net_Sample total: 63 errors
 Parsing done
 
 Rendering Global index.html
diff --git a/tests/phar/data/src/Foo.php b/tests/phar/data/src/Foo.php

Original file line number	Diff line number	Diff line change
`@@ -140,16 +140,18 @@ public static function abbrClass($class, bool $absolute = false): string`
`140`	`140`	`return sprintf('<abbr title="%s">%s</abbr>', htmlentities($class, ENT_QUOTES), htmlspecialchars($short));`
`141`	`141`	`}`
`142`	`142`
`143`		`- public function parseDesc(array $context, $desc, Reflection $classOrFunctionRefl)`
	`143`	`+ public function parseDesc(array $context, ?string $desc, Reflection $classOrFunctionRefl)`
`144`	`144`	`{`
`145`		`- if (!$desc) {`
	`145`	`+ if ($desc === null \|\| $desc === '') {`
`146`	`146`	`return $desc;`
`147`	`147`	`}`
`148`	`148`
`149`	`149`	`if (null === $this->markdown) {`
`150`	`150`	`$this->markdown = new Parsedown();`
`151`	`151`	`}`
`152`	`152`
	`153`	+ $desc = str_replace(['<code>', '</code>'], ['```', '```'], $desc);
	`154`	`+`
`153`	`155`	`// FIXME: the @see argument is more complex than just a class (Class::Method, local method directly, ...)`
`154`	`156`	`$desc = preg_replace_callback(`
`155`	`157`	`'/@see ([^ ]+)/',`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`	`use Doctum\Renderer\Diff;`
`8`	`8`	`use Doctum\Tests\AbstractTestCase;`
`9`	`9`
`10`		`-class RendererTest extends AbstractTestCase`
	`10`	`+class DiffTest extends AbstractTestCase`
`11`	`11`	`{`
`12`	`12`
`13`	`13`	`public function testIsPhpClass(): void`