fix: make <code> tags use fences

Author: williamdes

phpstan-baseline.neon

@@ -2235,11 +2235,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

src/Renderer/TwigExtension.php

@@ -138,16 +138,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 ([^ ]+)/',

tests/Renderer/TwigExtensionTest.php

@@ -78,7 +78,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>'
+            ],
         ];
     }