Warn when a class synopsis page doesn't exist

Author: kocsismate

Zend/zend_builtin_functions.stub.php

@@ -2,6 +2,7 @@
 
 /** @generate-class-entries */
 
+/** @undocumentable */
 #[\AllowDynamicProperties]
 class stdClass
 {

Zend/zend_builtin_functions_arginfo.h

@@ -2453,6 +2453,8 @@ class ClassInfo {
     public $cond;
     /** @var int|null */
     public $phpVersionIdMinimumCompatibility;
+    /** @var bool */
+    public $isUndocumentable;
 
     /**
      * @param AttributeInfo[] $attributes
@@ -2480,7 +2482,8 @@ public function __construct(
         array $funcInfos,
         array $enumCaseInfos,
         ?string $cond,
-        ?int $minimumPhpVersionIdCompatibility
+        ?int $minimumPhpVersionIdCompatibility,
+        bool $isUndocumentable
     ) {
         $this->name = $name;
         $this->flags = $flags;
@@ -2499,6 +2502,7 @@ public function __construct(
         $this->enumCaseInfos = $enumCaseInfos;
         $this->cond = $cond;
         $this->phpVersionIdMinimumCompatibility = $minimumPhpVersionIdCompatibility;
+        $this->isUndocumentable = $isUndocumentable;
     }
 
     /**
@@ -3088,6 +3092,8 @@ class FileInfo {
     public $generateLegacyArginfoForPhpVersionId;
     /** @var bool */
     public $generateClassEntries = false;
+    /** @var bool */
+    public $isUndocumentable = false;
 
     /**
      * @return iterable<FuncInfo>
@@ -3499,7 +3505,8 @@ function parseClass(
     array $methods,
     array $enumCases,
     ?string $cond,
-    ?int $minimumPhpVersionIdCompatibility
+    ?int $minimumPhpVersionIdCompatibility,
+    bool $isUndocumentable
 ): ClassInfo {
     $flags = $class instanceof Class_ ? $class->flags : 0;
     $comment = $class->getDocComment();
@@ -3521,6 +3528,8 @@ function parseClass(
                 $isStrictProperties = true;
             } else if ($tag->name === 'not-serializable') {
                 $isNotSerializable = true;
+            } else if ($tag->name === 'undocumentable') {
+                $isUndocumentable = true;
             }
         }
     }
@@ -3579,7 +3588,8 @@ function parseClass(
         $methods,
         $enumCases,
         $cond,
-        $minimumPhpVersionIdCompatibility
+        $minimumPhpVersionIdCompatibility,
+        $isUndocumentable
     );
 }
 
@@ -3732,7 +3742,7 @@ function handleStatements(FileInfo $fileInfo, array $stmts, PrettyPrinterAbstrac
             }
 
             $fileInfo->classInfos[] = parseClass(
-                $className, $stmt, $constInfos, $propertyInfos, $methodInfos, $enumCaseInfos, $cond, $fileInfo->generateLegacyArginfoForPhpVersionId
+                $className, $stmt, $constInfos, $propertyInfos, $methodInfos, $enumCaseInfos, $cond, $fileInfo->generateLegacyArginfoForPhpVersionId, $fileInfo->isUndocumentable
             );
             continue;
         }
@@ -3783,6 +3793,8 @@ protected function pName_FullyQualified(Name\FullyQualified $node) {
             } else if ($tag->name === 'generate-class-entries') {
                 $fileInfo->generateClassEntries = true;
                 $fileInfo->declarationPrefix = $tag->value ? $tag->value . " " : "";
+            } else if ($tag->name === 'undocumentable') {
+                $fileInfo->isUndocumentable = true;
             }
         }
     }
@@ -4219,12 +4231,14 @@ function generateClassSynopses(array $classMap, iterable $allConstInfos): array
 }
 
 /**
- * @param ClassInfo[] $classMap
+ * @param array<string, ClassInfo> $classMap
  * $param iterable<ConstInfo> $allConstInfos
  * @return array<string, string>
  */
 function replaceClassSynopses(string $targetDirectory, array $classMap, iterable $allConstInfos): array
 {
+    $existingClassSynopses = [];
+
     $classSynopses = [];
 
     $it = new RecursiveIteratorIterator(
@@ -4281,6 +4295,9 @@ function replaceClassSynopses(string $targetDirectory, array $classMap, iterable
             if (!isset($classMap[$className])) {
                 continue;
             }
+
+            $existingClassSynopses[$className] = $className;
+
             $classInfo = $classMap[$className];
 
             $newClassSynopsis = $classInfo->getClassSynopsisElement($doc, $classMap, $allConstInfos);
@@ -4320,6 +4337,14 @@ function replaceClassSynopses(string $targetDirectory, array $classMap, iterable
         }
     }
 
+    $missingClassSynopses = array_diff_key($classMap, $existingClassSynopses);
+    foreach ($missingClassSynopses as $className => $info) {
+        /** @var ClassInfo $info */
+        if (!$info->isUndocumentable) {
+            echo "Warning: Missing class synopsis page for $className\n";
+        }
+    }
+
     return $classSynopses;
 }
 

build/gen_stub.php

@@ -2,7 +2,10 @@
 
 /** @generate-function-entries */
 
-// These are extension methods for PDO. This is not a real class.
+/**
+ * These are extension methods for PDO. This is not a real class.
+ * @undocumentable
+ */
 class PDO_PGSql_Ext {
     /** @tentative-return-type */
     public function pgsqlCopyFromArray(string $tableName, array $rows, string $separator = "\t", string $nullAs = "\\\\N", ?string $fields = null): bool {}

ext/pdo_pgsql/pgsql_driver.stub.php

@@ -2,7 +2,10 @@
 
 /** @generate-function-entries */
 
-// These are extension methods for PDO. This is not a real class.
+/**
+ * These are extension methods for PDO. This is not a real class.
+ * @undocumentable
+ */
 class PDO_SQLite_Ext {
     /** @tentative-return-type */
     public function sqliteCreateFunction(string $name, callable $callback, int $numArgs = -1, int $flags = 0): bool {}

ext/pdo_pgsql/pgsql_driver_arginfo.h

@@ -740,6 +740,7 @@
 const LOG_PERROR = UNKNOWN;
 #endif
 
+/** @undocumentable */
 #[AllowDynamicProperties]
 final class __PHP_Incomplete_Class
 {

ext/pdo_sqlite/sqlite_driver.stub.php

@@ -1,6 +1,9 @@
 <?php
 
-/** @generate-class-entries static */
+/**
+ * @generate-class-entries static
+ * @undocumentable
+ */
 
 final class _ZendTestFiber
 {

ext/pdo_sqlite/sqlite_driver_arginfo.h

@@ -3,6 +3,7 @@
 /**
  * @generate-class-entries static
  * @generate-legacy-arginfo 80000
+ * @undocumentable
  */
 namespace {
     /**