4.0 | Generators/Generator: improve error messages

Make errors encountered when processing XML documentation more informative by providing more specific error messages via a dedicated `GeneratorException`, which extends the PHP native `DomainException`.

Ref:
* https://www.php.net/class.domainexception

Author: jrfnl

src/Exceptions/GeneratorException.php

@@ -0,0 +1,18 @@
+<?php
+/**
+ * An exception thrown by PHP_CodeSniffer when it encounters an error in the XML document being processed
+ * by one of the documentation Generators.
+ *
+ * @author    Juliette Reinders Folmer <[email protected]>
+ * @copyright 2024 PHPCSStandards and contributors
+ * @license   https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
+ */
+
+namespace PHP_CodeSniffer\Exceptions;
+
+use DomainException;
+
+class GeneratorException extends DomainException
+{
+
+}//end class

src/Generators/Generator.php

@@ -15,8 +15,10 @@
 namespace PHP_CodeSniffer\Generators;
 
 use DOMDocument;
+use DOMElement;
 use DOMNode;
 use PHP_CodeSniffer\Autoload;
+use PHP_CodeSniffer\Exceptions\GeneratorException;
 use PHP_CodeSniffer\Ruleset;
 
 abstract class Generator
@@ -112,13 +114,22 @@ protected function getTitle(DOMNode $doc)
      *
      * @return void
      * @see    processSniff()
+     *
+     * @throws \PHP_CodeSniffer\Exceptions\GeneratorException If there is no <documentation> element
+     *                                                        in the XML document.
      */
     public function generate()
     {
         foreach ($this->docFiles as $file) {
             $doc = new DOMDocument();
             $doc->load($file);
             $documentation = $doc->getElementsByTagName('documentation')->item(0);
+            if (($documentation instanceof DOMNode) === false) {
+                throw new GeneratorException(
+                    'Missing top-level <documentation> element in XML documentation file '.$file
+                );
+            }
+
             $this->processSniff($documentation);
         }
 

src/Generators/HTML.php

@@ -19,6 +19,7 @@
 use DOMElement;
 use DOMNode;
 use PHP_CodeSniffer\Config;
+use PHP_CodeSniffer\Exceptions\GeneratorException;
 
 class HTML extends Generator
 {
@@ -126,6 +127,9 @@ class HTML extends Generator
      *
      * @return void
      * @see    processSniff()
+     *
+     * @throws \PHP_CodeSniffer\Exceptions\GeneratorException If there is no <documentation> element
+     *                                                        in the XML document.
      */
     public function generate()
     {
@@ -134,10 +138,18 @@ public function generate()
         }
 
         ob_start();
-        parent::generate();
+        try {
+            parent::generate();
+            $content = ob_get_clean();
+        } catch (GeneratorException $e) {
+            ob_end_clean();
+            $content = '';
+        }
 
-        $content = ob_get_contents();
-        ob_end_clean();
+        // If an exception was caught, rethrow it outside of the output buffer.
+        if (isset($e) === true) {
+            throw $e;
+        }
 
         // Clear anchor cache after Documentation generation.
         // The anchor generation for the TOC anchor links will use the same logic, so should end up with the same unique slugs.

src/Generators/Markdown.php

@@ -14,6 +14,7 @@
 use DOMElement;
 use DOMNode;
 use PHP_CodeSniffer\Config;
+use PHP_CodeSniffer\Exceptions\GeneratorException;
 
 class Markdown extends Generator
 {
@@ -24,6 +25,9 @@ class Markdown extends Generator
      *
      * @return void
      * @see    processSniff()
+     *
+     * @throws \PHP_CodeSniffer\Exceptions\GeneratorException If there is no <documentation> element
+     *                                                        in the XML document.
      */
     public function generate()
     {
@@ -32,10 +36,18 @@ public function generate()
         }
 
         ob_start();
-        parent::generate();
+        try {
+            parent::generate();
+            $content = ob_get_clean();
+        } catch (GeneratorException $e) {
+            ob_end_clean();
+            $content = '';
+        }
 
-        $content = ob_get_contents();
-        ob_end_clean();
+        // If an exception was caught, rethrow it outside of the output buffer.
+        if (isset($e) === true) {
+            throw $e;
+        }
 
         if (trim($content) !== '') {
             echo $this->getFormattedHeader();

tests/Core/Generators/GeneratorTest.php

@@ -8,6 +8,7 @@
 
 namespace PHP_CodeSniffer\Tests\Core\Generators;
 
+use PHP_CodeSniffer\Exceptions\GeneratorException;
 use PHP_CodeSniffer\Ruleset;
 use PHP_CodeSniffer\Tests\ConfigDouble;
 use PHP_CodeSniffer\Tests\Core\Generators\Fixtures\MockGenerator;
@@ -94,8 +95,6 @@ public static function dataConstructor()
     /**
      * Verify that an XML doc which isn't valid documentation yields an Exception to warn devs.
      *
-     * This should not be hidden via defensive coding!
-     *
      * @return void
      */
     public function testGeneratingInvalidDocsResultsInException()
@@ -105,14 +104,8 @@ public function testGeneratingInvalidDocsResultsInException()
         $config   = new ConfigDouble(["--standard=$standard"]);
         $ruleset  = new Ruleset($config);
 
-        if (PHP_VERSION_ID >= 80000) {
-            $message = 'processSniff(): Argument #1 ($doc) must be of type DOMNode, null given';
-        } else {
-            $message = 'processSniff() must be an instance of DOMNode, null given';
-        }
-
-        $this->expectException('TypeError');
-        $this->expectExceptionMessage($message);
+        $this->expectException(GeneratorException::class);
+        $this->expectExceptionMessage('Missing top-level <documentation> element in XML documentation file');
 
         $generator = new MockGenerator($ruleset);
         $generator->generate();

tests/Core/Generators/HTMLTest.php

@@ -8,6 +8,8 @@
 
 namespace PHP_CodeSniffer\Tests\Core\Generators;
 
+use PHP_CodeSniffer\Exceptions\GeneratorException;
+use PHP_CodeSniffer\Generators\HTML;
 use PHP_CodeSniffer\Ruleset;
 use PHP_CodeSniffer\Tests\ConfigDouble;
 use PHP_CodeSniffer\Tests\Core\Generators\Fixtures\HTMLDouble;
@@ -23,6 +25,27 @@ final class HTMLTest extends TestCase
 {
 
 
+    /**
+     * Verify that an XML doc which isn't valid documentation yields an Exception to warn devs.
+     *
+     * @return void
+     */
+    public function testGeneratingInvalidDocsResultsInException()
+    {
+        // Set up the ruleset.
+        $standard = __DIR__.'/NoValidDocsTest.xml';
+        $config   = new ConfigDouble(["--standard=$standard"]);
+        $ruleset  = new Ruleset($config);
+
+        $this->expectException(GeneratorException::class);
+        $this->expectExceptionMessage('Missing top-level <documentation> element in XML documentation file');
+
+        $generator = new HTML($ruleset);
+        $generator->generate();
+
+    }//end testGeneratingInvalidDocsResultsInException()
+
+
     /**
      * Test the generated docs.
      *

tests/Core/Generators/MarkdownTest.php

@@ -8,6 +8,8 @@
 
 namespace PHP_CodeSniffer\Tests\Core\Generators;
 
+use PHP_CodeSniffer\Exceptions\GeneratorException;
+use PHP_CodeSniffer\Generators\Markdown;
 use PHP_CodeSniffer\Ruleset;
 use PHP_CodeSniffer\Tests\ConfigDouble;
 use PHP_CodeSniffer\Tests\Core\Generators\Fixtures\MarkdownDouble;
@@ -23,6 +25,27 @@ final class MarkdownTest extends TestCase
 {
 
 
+    /**
+     * Verify that an XML doc which isn't valid documentation yields an Exception to warn devs.
+     *
+     * @return void
+     */
+    public function testGeneratingInvalidDocsResultsInException()
+    {
+        // Set up the ruleset.
+        $standard = __DIR__.'/NoValidDocsTest.xml';
+        $config   = new ConfigDouble(["--standard=$standard"]);
+        $ruleset  = new Ruleset($config);
+
+        $this->expectException(GeneratorException::class);
+        $this->expectExceptionMessage('Missing top-level <documentation> element in XML documentation file');
+
+        $generator = new Markdown($ruleset);
+        $generator->generate();
+
+    }//end testGeneratingInvalidDocsResultsInException()
+
+
     /**
      * Test the generated docs.
      *