From ccc863639e399ae4d40ed35ac4707e73bae28ae7 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sat, 30 Sep 2023 03:35:44 +0100
Subject: [PATCH 01/15] [skip ci] gen_stub: Generate useful methodsynopsises

So that they can be used as a starting point for new functions/methods.
---
 build/gen_stub.php | 313 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 303 insertions(+), 10 deletions(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index eaf4af0a6ac98..5f968ef2dd682 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1060,7 +1060,7 @@ public function getArgInfoName(): string {
     }
 
     public function getMethodSynopsisFilename(): string {
-        return implode('_', $this->name->getParts());
+        return 'functions/' . implode('/', str_replace('_', '-', $this->name->getParts()));
     }
 
     public function getNameForAttributes(): string {
@@ -1105,8 +1105,11 @@ public function getArgInfoName(): string {
         return "arginfo_class_{$this->getDeclarationClassName()}_{$this->methodName}";
     }
 
-    public function getMethodSynopsisFilename(): string {
-        return $this->getDeclarationClassName() . "_{$this->methodName}";
+    public function getMethodSynopsisFilename(): string
+    {
+        $parts = [...$this->className->getParts(), ltrim($this->methodName, '_')];
+        /* File paths are in lowercase */
+        return implode('/', array_map('strtolower', $parts));
     }
 
     public function getNameForAttributes(): string {
@@ -1486,17 +1489,300 @@ private function getFlagsAsArginfoString(): string
      * @throws Exception
      */
     public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?string {
-
-        $doc = new DOMDocument();
+        $doc = new DOMDocument("1.0", "utf-8");
         $doc->formatOutput = true;
+
+        $refentry = $doc->createElement('refentry');
+        $doc->appendChild($refentry);
+
+        if ($this->isMethod()) {
+            assert($this->name instanceof MethodName);
+            $id = $doc->createAttribute("xml:id");
+            $id->value = addslashes(strtolower($this->name->className->__toString())) . '.' . strtolower($this->name->methodName);
+            $refentry->appendChild($id);
+        } else {
+            // TODO Functions
+        }
+        $refentry->setAttribute("xmlns", "http://docbook.org/ns/docbook");
+        $refentry->appendChild(new DOMText("\n "));
+
+        /* Creation of <refnamediv> */
+        $refnamediv = $doc->createElement('refnamediv');
+        $refnamediv->appendChild(new DOMText("\n  "));
+        if ($this->isMethod()) {
+            assert($this->name instanceof MethodName);
+            $refname = $doc->createElement('refname', $this->name->className->__toString() . '::' . $this->name->methodName);
+            $refnamediv->appendChild($refname);
+        } else {
+            // TODO Functions
+        }
+        $refnamediv->appendChild(new DOMText("\n  "));
+        $refpurpose = $doc->createElement('refpurpose', 'Description');
+        $refnamediv->appendChild($refpurpose);
+
+        $refnamediv->appendChild(new DOMText("\n "));
+        $refentry->appendChild($refnamediv);
+        $refentry->appendChild(new DOMText("\n\n "));
+
+        /* Creation of <refsect1 role="description"> */
+        $descriptionRefSec = $doc->createElement('refsect1');
+        $descriptionRefSec->setAttribute('role', 'description');
+        $descriptionRefSec->appendChild(new DOMText("\n  "));
+        $refTitleDescription = $doc->createEntityReference('reftitle.description');
+        $descriptionRefSec->appendChild($refTitleDescription);
+        $descriptionRefSec->appendChild(new DOMText("\n  "));
+
         $methodSynopsis = $this->getMethodSynopsisElement($funcMap, $aliasMap, $doc);
         if (!$methodSynopsis) {
             return null;
         }
+        $descriptionRefSec->appendChild($methodSynopsis);
+        $descriptionRefSec->appendChild(new DOMText("\n  "));
+        $undocumentedEntity = $doc->createEntityReference('warn.undocumented.func');
+        $descriptionRefSec->appendChild($undocumentedEntity);
+        $descriptionRefSec->appendChild(new DOMText("\n  "));
+        $returnDescriptionPara = $doc->createElement('para');
+        $returnDescriptionPara->appendChild(new DOMText("\n   Description\n  "));
+        $descriptionRefSec->appendChild($returnDescriptionPara);
+
+        $descriptionRefSec->appendChild(new DOMText("\n "));
+        $refentry->appendChild($descriptionRefSec);
+        $refentry->appendChild(new DOMText("\n\n "));
+
+        /* Creation of <refsect1 role="parameters"> */
+        $parametersRefSec = $this->getParameterSection($doc);
+        $refentry->appendChild($parametersRefSec);
+        $refentry->appendChild(new DOMText("\n\n "));
+
+        /* Creation of <refsect1 role="returnvalues"> */
+        $returnRefSec = $this->getReturnValueSection($doc);
+        $refentry->appendChild($returnRefSec);
+        $refentry->appendChild(new DOMText("\n\n "));
+
+        /* Creation of <refsect1 role="errors"> */
+        $errorsRefSec = $doc->createElement('refsect1');
+        $errorsRefSec->setAttribute('role', 'errors');
+        $errorsRefSec->appendChild(new DOMText("\n  "));
+        $refTitleErrors = $doc->createEntityReference('reftitle.errors');
+        $errorsRefSec->appendChild($refTitleErrors);
+        $errorsRefSec->appendChild(new DOMText("\n  "));
+        $errorsDescriptionPara = $doc->createElement('para');
+        $errorsDescriptionPara->appendChild(new DOMText("\n   When does this function issue E_* level errors, and/or throw exceptions.\n  "));
+        $errorsRefSec->appendChild($errorsDescriptionPara);
+        $errorsRefSec->appendChild(new DOMText("\n "));
+
+        $refentry->appendChild($errorsRefSec);
+        $refentry->appendChild(new DOMText("\n\n "));
+
+        /* Creation of <refsect1 role="changelog"> */
+        $changelogRefSec = $this->getChangelogSection($doc);
+        $refentry->appendChild($changelogRefSec);
+
+        // TODO Examples, Notes, and See Also sections
+
+        $refentry->appendChild(new DOMText("\n\n"));
+
+        $doc->appendChild(new DOMComment(
+            <<<ENDCOMMENT
+Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+
+ENDCOMMENT
+        ));
+        return $doc->saveXML();
+    }
 
-        $doc->appendChild($methodSynopsis);
+    private function getParameterSection(DOMDocument $doc): DOMElement {
+        $parametersRefSec = $doc->createElement('refsect1');
+        $parametersRefSec->setAttribute('role', 'parameters');
+        $parametersRefSec->appendChild(new DOMText("\n  "));
+        $refTitle = $doc->createEntityReference('reftitle.parameters');
+        $parametersRefSec->appendChild($refTitle);
+        $parametersRefSec->appendChild(new DOMText("\n  "));
+        if (empty($this->args)) {
+            $noParamEntity = $doc->createEntityReference('no.function.parameters');
+            $parametersRefSec->appendChild($noParamEntity);
+            return $parametersRefSec;
+        } else {
+            $parametersPara = $doc->createElement('para');
+            $parametersRefSec->appendChild($parametersPara);
+
+            $parametersPara->appendChild(new DOMText("\n   "));
+            $parametersList = $doc->createElement('variablelist');
+            $parametersPara->appendChild($parametersList);
+
+            /*
+            <varlistentry>
+             <term><parameter>name</parameter></term>
+             <listitem>
+              <para>
+               Description.
+              </para>
+             </listitem>
+            </varlistentry>
+            */
+            foreach ($this->args as $arg) {
+                $parameter = $doc->createElement('parameter', $arg->name);
+                $parameterTerm = $doc->createElement('term');
+                $parameterTerm->appendChild($parameter);
+
+                $parameterEntry = $doc->createElement('varlistentry');
+                $parameterEntry->appendChild(new DOMText("\n     "));
+                $parameterEntry->appendChild($parameterTerm);
+                $parameterEntry->appendChild(new DOMText("\n     "));
+
+                $listItemPara = $doc->createElement('para');
+                $listItemPara->appendChild(new DOMText("\n       "));
+                $listItemPara->appendChild(new DOMText("Description."));
+                $listItemPara->appendChild(new DOMText("\n      "));
+
+                $parameterEntryListItem = $doc->createElement('listitem');
+                $parameterEntryListItem->appendChild(new DOMText("\n      "));
+                $parameterEntryListItem->appendChild($listItemPara);
+                $parameterEntryListItem->appendChild(new DOMText("\n     "));
+
+                $parameterEntry->appendChild($parameterEntryListItem);
+                $parameterEntry->appendChild(new DOMText("\n    "));
+
+                $parametersList->appendChild($parameterEntry);
+                $parametersList->appendChild(new DOMText("\n   "));
+            }
+        }
+        $parametersPara->appendChild(new DOMText("\n  "));
+        $parametersRefSec->appendChild(new DOMText("\n "));
+        return $parametersRefSec;
+    }
+
+    private function getReturnValueSection(DOMDocument $doc): DOMElement {
+        $returnRefSec = $doc->createElement('refsect1');
+        $returnRefSec->setAttribute('role', 'returnvalues');
+        $returnRefSec->appendChild(new DOMText("\n  "));
+        $refTitle = $doc->createEntityReference('reftitle.returnvalues');
+        $returnRefSec->appendChild($refTitle);
+        $returnRefSec->appendChild(new DOMText("\n  "));
+        $returnDescriptionPara = $doc->createElement('para');
+        $returnDescriptionPara->appendChild(new DOMText("\n   "));
+
+        $returnType = $this->return->type;
+        if ($returnType === null) {
+            $returnDescriptionPara->appendChild(new DOMText("Description"));
+        } else if (count($returnType->types) === 1) {
+            $type = $returnType->types[0];
+            $name = $type->name;
+            $descriptionNode = match ($name) {
+                'void' => $doc->createEntityReference('return.void'),
+                'true' => $doc->createEntityReference('return.true.always'),
+                'bool' => $doc->createEntityReference('return.success'),
+                default => new DOMText("Description"),
+            };
+            $returnDescriptionPara->appendChild($descriptionNode);
+        } else {
+            $returnDescriptionPara->appendChild(new DOMText("Description"));
+        }
+        $returnDescriptionPara->appendChild(new DOMText("\n  "));
+        $returnRefSec->appendChild($returnDescriptionPara);
+        $returnRefSec->appendChild(new DOMText("\n "));
+        return $returnRefSec;
+    }
 
-        return $doc->saveXML();
+    /**
+     * @param array<DOMNode> $headers [count($headers) === $columns]
+     * @param array<array<DOMNode>> $rows [count($rows[$i]) === $columns]
+     */
+    private function generateDocbookInformalTable(
+        DOMDocument $doc,
+        int $indent,
+        int $columns,
+        array $headers,
+        array $rows
+    ): DOMElement {
+        $strIndent = str_repeat(' ', $indent);
+
+        $headerRow = $doc->createElement('row');
+        foreach ($headers as $header) {
+            $headerEntry = $doc->createElement('entry');
+            $headerEntry->appendChild($header);
+
+            $headerRow->appendChild(new DOMText("\n$strIndent    "));
+            $headerRow->appendChild($headerEntry);
+        }
+        $headerRow->appendChild(new DOMText("\n$strIndent   "));
+
+        $thead = $doc->createElement('thead');
+        $thead->appendChild(new DOMText("\n$strIndent   "));
+        $thead->appendChild($headerRow);
+        $thead->appendChild(new DOMText("\n$strIndent  "));
+
+        $tbody = $doc->createElement('tbody');
+        foreach ($rows as $row) {
+            $bodyRow = $doc->createElement('row');
+            foreach ($row as $cell) {
+                $entry = $doc->createElement('entry');
+                $entry->appendChild($cell);
+
+                $bodyRow->appendChild(new DOMText("\n$strIndent    "));
+                $bodyRow->appendChild($entry);
+            }
+            $bodyRow->appendChild(new DOMText("\n$strIndent   "));
+
+            $tbody->appendChild(new DOMText("\n$strIndent   "));
+            $tbody->appendChild($bodyRow);
+            $tbody->appendChild(new DOMText("\n$strIndent  "));
+        }
+
+        $tgroup = $doc->createElement('tgroup');
+        $tgroup->setAttribute('cols', (string) $columns);
+        $tgroup->appendChild(new DOMText("\n$strIndent  "));
+        $tgroup->appendChild($thead);
+        $tgroup->appendChild(new DOMText("\n$strIndent  "));
+        $tgroup->appendChild($tbody);
+        $tgroup->appendChild(new DOMText("\n$strIndent "));
+
+        $table = $doc->createElement('informaltable');
+        $table->appendChild(new DOMText("\n$strIndent "));
+        $table->appendChild($tgroup);
+        $table->appendChild(new DOMText("\n$strIndent"));
+
+        return $table;
+    }
+
+    private function getChangelogSection(DOMDocument $doc): DOMElement {
+        $refSec = $doc->createElement('refsect1');
+        $refSec->setAttribute('role', 'changelog');
+        $refSec->appendChild(new DOMText("\n  "));
+        $refTitle = $doc->createEntityReference('reftitle.changelog');
+        $refSec->appendChild($refTitle);
+        $refSec->appendChild(new DOMText("\n  "));
+        $headers = [
+            $doc->createEntityReference('Version'),
+            $doc->createEntityReference('Description'),
+        ];
+        $rows = [[
+            new DOMText('8.X.0'),
+            new DOMText("\n       Description\n      "),
+        ]];
+        $table = $this->generateDocbookInformalTable($doc, indent: 2, columns: 2, headers: $headers, rows: $rows);
+        $refSec->appendChild($table);
+
+        $refSec->appendChild(new DOMText("\n "));
+        return $refSec;
     }
 
     /**
@@ -5361,7 +5647,12 @@ function(?ArgInfo $aliasArg, ?ArgInfo $aliasedArg) use ($aliasFunc, $aliasedFunc
 }
 
 if ($generateMethodSynopses) {
-    $methodSynopsesDirectory = getcwd() . "/methodsynopses";
+    // Use the manual as target if we are targeting a specific extension
+    if (str_contains($manualTarget, 'reference')) {
+        $methodSynopsesDirectory = $manualTarget;
+    } else {
+        $methodSynopsesDirectory = getcwd() . "/methodsynopses";
+    }
 
     $methodSynopses = generateMethodSynopses($funcMap, $aliasMap);
     if (!empty($methodSynopses)) {
@@ -5370,8 +5661,10 @@ function(?ArgInfo $aliasArg, ?ArgInfo $aliasedArg) use ($aliasFunc, $aliasedFunc
         }
 
         foreach ($methodSynopses as $filename => $content) {
-            if (file_put_contents("$methodSynopsesDirectory/$filename", $content)) {
-                echo "Saved $filename\n";
+            if (!file_exists("$methodSynopsesDirectory/$filename")) {
+                if (file_put_contents("$methodSynopsesDirectory/$filename", $content)) {
+                    echo "Saved $filename\n";
+                }
             }
         }
     }

From b9c457d80c68cb7923e8bbe46ae6a5eb11a2dd40 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sat, 30 Sep 2023 16:45:45 +0100
Subject: [PATCH 02/15] [skip ci] Use __toString() directly
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Máté Kocsis <kocsismate@woohoolabs.com>
---
 build/gen_stub.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index 5f968ef2dd682..4800763cb3240 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1511,7 +1511,7 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         $refnamediv->appendChild(new DOMText("\n  "));
         if ($this->isMethod()) {
             assert($this->name instanceof MethodName);
-            $refname = $doc->createElement('refname', $this->name->className->__toString() . '::' . $this->name->methodName);
+            $refname = $doc->createElement('refname', $this->name->__toString());
             $refnamediv->appendChild($refname);
         } else {
             // TODO Functions

From a54366556e6d34ad09556a4644f54fc5acc49659 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sat, 30 Sep 2023 17:27:17 +0100
Subject: [PATCH 03/15] Tweak generated document

Do not emit a return value section for constructors and destructors
Improve ID and refname generation for methods and support functions (?)
---
 build/gen_stub.php | 31 +++++++++++++++++--------------
 1 file changed, 17 insertions(+), 14 deletions(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index 4800763cb3240..4537f9f4e7961 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1495,27 +1495,28 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         $refentry = $doc->createElement('refentry');
         $doc->appendChild($refentry);
 
+        $id = $doc->createAttribute("xml:id");
         if ($this->isMethod()) {
             assert($this->name instanceof MethodName);
-            $id = $doc->createAttribute("xml:id");
-            $id->value = addslashes(strtolower($this->name->className->__toString())) . '.' . strtolower($this->name->methodName);
-            $refentry->appendChild($id);
+            /* Namespaces are seperated by '-', '_' must be converted to '-' too.
+             * Trim away the __ for magic methods */
+            $id->value = strtolower(
+                str_replace('\\', '-', $this->name->className->__toString())
+                . '.'
+                . str_replace('_', '-', ltrim($this->name->methodName, '_'))
+            );
         } else {
-            // TODO Functions
+            $id->value = 'function.' . strtolower(str_replace('_', '-', $this->name->__toString()));
         }
+        $refentry->appendChild($id);
         $refentry->setAttribute("xmlns", "http://docbook.org/ns/docbook");
         $refentry->appendChild(new DOMText("\n "));
 
         /* Creation of <refnamediv> */
         $refnamediv = $doc->createElement('refnamediv');
         $refnamediv->appendChild(new DOMText("\n  "));
-        if ($this->isMethod()) {
-            assert($this->name instanceof MethodName);
-            $refname = $doc->createElement('refname', $this->name->__toString());
-            $refnamediv->appendChild($refname);
-        } else {
-            // TODO Functions
-        }
+        $refname = $doc->createElement('refname', $this->name->__toString());
+        $refnamediv->appendChild($refname);
         $refnamediv->appendChild(new DOMText("\n  "));
         $refpurpose = $doc->createElement('refpurpose', 'Description');
         $refnamediv->appendChild($refpurpose);
@@ -1555,9 +1556,11 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         $refentry->appendChild(new DOMText("\n\n "));
 
         /* Creation of <refsect1 role="returnvalues"> */
-        $returnRefSec = $this->getReturnValueSection($doc);
-        $refentry->appendChild($returnRefSec);
-        $refentry->appendChild(new DOMText("\n\n "));
+        if (!$this->name->isConstructor() && !$this->name->isDestructor()) {
+            $returnRefSec = $this->getReturnValueSection($doc);
+            $refentry->appendChild($returnRefSec);
+            $refentry->appendChild(new DOMText("\n\n "));
+        }
 
         /* Creation of <refsect1 role="errors"> */
         $errorsRefSec = $doc->createElement('refsect1');

From 37603926c07d6a511947d9f9b79116270ea11fa1 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sat, 30 Sep 2023 17:42:32 +0100
Subject: [PATCH 04/15] Generate a basic See Also section

---
 build/gen_stub.php | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index 4537f9f4e7961..5bc8ab63212b7 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1580,8 +1580,37 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         /* Creation of <refsect1 role="changelog"> */
         $changelogRefSec = $this->getChangelogSection($doc);
         $refentry->appendChild($changelogRefSec);
+        $refentry->appendChild(new DOMText("\n\n "));
 
-        // TODO Examples, Notes, and See Also sections
+        // TODO Examples, and Notes sections
+
+        /* Creation of <refsect1 role="seealso"> */
+        $seeAlsoRefSec = $doc->createElement('refsect1');
+        $seeAlsoRefSec->setAttribute('role', 'seealso');
+        $seeAlsoRefSec->appendChild(new DOMText("\n  "));
+        $refTitleSeeAlso = $doc->createEntityReference('reftitle.seealso');
+        $seeAlsoRefSec->appendChild($refTitleSeeAlso);
+        $seeAlsoRefSec->appendChild(new DOMText("\n  "));
+
+        /* TODO Actually generate a markup for class names, functions and links?
+  <simplelist>
+   <member><methodname>ClassName::otherMethodName</methodname></member>
+   <member><function>some_function</function></member>
+   <member>The <link linkend="something">something appendix</link></member>
+  </simplelist>
+         */
+        $seeAlsoMember = $doc->createElement('member');
+        $seeAlsoMember->appendChild(new DOMText("Method name, function, or link to reference"));
+
+        $seeAlsoList = $doc->createElement('simplelist');
+        $seeAlsoList->appendChild(new DOMText("\n   "));
+        $seeAlsoList->appendChild($seeAlsoMember);
+        $seeAlsoList->appendChild(new DOMText("\n  "));
+
+        $seeAlsoRefSec->appendChild($seeAlsoList);
+        $seeAlsoRefSec->appendChild(new DOMText("\n "));
+
+        $refentry->appendChild($seeAlsoRefSec);
 
         $refentry->appendChild(new DOMText("\n\n"));
 

From 8f94266a719ecf42329e9e377a56546df3f77324 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sat, 30 Sep 2023 17:54:14 +0100
Subject: [PATCH 05/15] Fix parameter section indent

---
 build/gen_stub.php | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index 5bc8ab63212b7..6174944a17cdd 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1693,9 +1693,10 @@ private function getParameterSection(DOMDocument $doc): DOMElement {
                 $parameterEntry->appendChild($parameterEntryListItem);
                 $parameterEntry->appendChild(new DOMText("\n    "));
 
+                $parametersList->appendChild(new DOMText("\n    "));
                 $parametersList->appendChild($parameterEntry);
-                $parametersList->appendChild(new DOMText("\n   "));
             }
+            $parametersList->appendChild(new DOMText("\n   "));
         }
         $parametersPara->appendChild(new DOMText("\n  "));
         $parametersRefSec->appendChild(new DOMText("\n "));

From 98addd8b7931c43aa3f0e4522d729fe84d6f1787 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sat, 30 Sep 2023 18:26:06 +0100
Subject: [PATCH 06/15] [skip ci] Fix refentry attribute order

Use a creative solution because libxml otherwise forces xmlns to be the first one
---
 build/gen_stub.php | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index 6174944a17cdd..1d398657baedd 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1495,21 +1495,25 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         $refentry = $doc->createElement('refentry');
         $doc->appendChild($refentry);
 
-        $id = $doc->createAttribute("xml:id");
         if ($this->isMethod()) {
             assert($this->name instanceof MethodName);
             /* Namespaces are seperated by '-', '_' must be converted to '-' too.
              * Trim away the __ for magic methods */
-            $id->value = strtolower(
+            $id = strtolower(
                 str_replace('\\', '-', $this->name->className->__toString())
                 . '.'
                 . str_replace('_', '-', ltrim($this->name->methodName, '_'))
             );
         } else {
-            $id->value = 'function.' . strtolower(str_replace('_', '-', $this->name->__toString()));
-        }
-        $refentry->appendChild($id);
-        $refentry->setAttribute("xmlns", "http://docbook.org/ns/docbook");
+            $id = 'function.' . strtolower(str_replace('_', '-', $this->name->__toString()));
+        }
+        $refentry->setAttribute("xml:id", $id);
+        /* We create an attribute for xmlns, as libxml otherwise force it to be the first one */
+        //$refentry->setAttribute("xmlns", "http://docbook.org/ns/docbook");
+        $namespace = $doc->createAttribute('xmlns');
+        $namespace->value = "http://docbook.org/ns/docbook";
+        $refentry->setAttributeNode($namespace);
+        $refentry->setAttribute("xmlns:xlink", "http://www.w3.org/1999/xlink");
         $refentry->appendChild(new DOMText("\n "));
 
         /* Creation of <refnamediv> */

From 604c18923051c1b6eab6c8396913b0bff9329794 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sat, 30 Sep 2023 19:22:42 +0100
Subject: [PATCH 07/15] Generate example section

---
 build/gen_stub.php | 81 +++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 69 insertions(+), 12 deletions(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index 1d398657baedd..1cf133401815f 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1489,6 +1489,8 @@ private function getFlagsAsArginfoString(): string
      * @throws Exception
      */
     public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?string {
+        $REFSEC1_SEPERATOR = "\n\n ";
+
         $doc = new DOMDocument("1.0", "utf-8");
         $doc->formatOutput = true;
 
@@ -1526,8 +1528,7 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         $refnamediv->appendChild($refpurpose);
 
         $refnamediv->appendChild(new DOMText("\n "));
-        $refentry->appendChild($refnamediv);
-        $refentry->appendChild(new DOMText("\n\n "));
+        $refentry->append($refnamediv, $REFSEC1_SEPERATOR);
 
         /* Creation of <refsect1 role="description"> */
         $descriptionRefSec = $doc->createElement('refsect1');
@@ -1551,19 +1552,16 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         $descriptionRefSec->appendChild($returnDescriptionPara);
 
         $descriptionRefSec->appendChild(new DOMText("\n "));
-        $refentry->appendChild($descriptionRefSec);
-        $refentry->appendChild(new DOMText("\n\n "));
+        $refentry->append($descriptionRefSec, $REFSEC1_SEPERATOR);
 
         /* Creation of <refsect1 role="parameters"> */
         $parametersRefSec = $this->getParameterSection($doc);
-        $refentry->appendChild($parametersRefSec);
-        $refentry->appendChild(new DOMText("\n\n "));
+        $refentry->append($parametersRefSec, $REFSEC1_SEPERATOR);
 
         /* Creation of <refsect1 role="returnvalues"> */
         if (!$this->name->isConstructor() && !$this->name->isDestructor()) {
             $returnRefSec = $this->getReturnValueSection($doc);
-            $refentry->appendChild($returnRefSec);
-            $refentry->appendChild(new DOMText("\n\n "));
+            $refentry->append($returnRefSec, $REFSEC1_SEPERATOR);
         }
 
         /* Creation of <refsect1 role="errors"> */
@@ -1578,15 +1576,15 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         $errorsRefSec->appendChild($errorsDescriptionPara);
         $errorsRefSec->appendChild(new DOMText("\n "));
 
-        $refentry->appendChild($errorsRefSec);
-        $refentry->appendChild(new DOMText("\n\n "));
+        $refentry->append($errorsRefSec, $REFSEC1_SEPERATOR);
 
         /* Creation of <refsect1 role="changelog"> */
         $changelogRefSec = $this->getChangelogSection($doc);
-        $refentry->appendChild($changelogRefSec);
-        $refentry->appendChild(new DOMText("\n\n "));
+        $refentry->append($changelogRefSec, $REFSEC1_SEPERATOR);
 
         // TODO Examples, and Notes sections
+        $exampleRefSec = $this->getExampleSection($doc);
+        $refentry->append($exampleRefSec, $REFSEC1_SEPERATOR);
 
         /* Creation of <refsect1 role="seealso"> */
         $seeAlsoRefSec = $doc->createElement('refsect1');
@@ -1822,6 +1820,65 @@ private function getChangelogSection(DOMDocument $doc): DOMElement {
         return $refSec;
     }
 
+    private function getExampleSection(DOMDocument $doc): DOMElement {
+        $refSec = $doc->createElement('refsect1');
+        $refSec->setAttribute('role', 'examples');
+        $refTitle = $doc->createEntityReference('reftitle.examples');
+        $refSec->append("\n  ", $refTitle);
+
+        $example = $doc->createElement('example');
+        $example->setAttribute('xml:id', 'func-or-method-name.example.basic');
+
+        $title = $doc->createElement('title');
+        $fn = $doc->createElement($this->isMethod() ? 'methodname' : 'function');
+        $fn->append($this->name->__toString());
+        $title->append($fn, ' example');
+
+        $example->append("\n   ", $title);
+
+        $para = $doc->createElement('para');
+        $para->append("\n    ", "Description.", "\n   ");
+        $example->append("\n   ", $para);
+
+        $prog = $doc->createElement('programlisting');
+        $prog->setAttribute('role', 'php');
+        $code = new DOMCdataSection(
+            <<<CODE_EXAMPLE
+
+<?php
+echo "Code example";
+?>
+
+CODE_EXAMPLE
+        );
+        $prog->append("\n");
+        $prog->appendChild($code);
+        $prog->append("\n   ");
+
+        $example->append("\n   ", $prog);
+        $example->append("\n   ", $doc->createEntityReference('example.outputs'));
+
+        $output = new DOMCdataSection(
+            <<<OUPUT_EXAMPLE
+
+Code example
+
+OUPUT_EXAMPLE
+        );
+        $screen = $doc->createElement('screen');
+        $screen->append("\n");
+        $screen->appendChild($output);
+        $screen->append("\n   ");
+
+        $example->append("\n   ", $screen);
+        $example->append("\n  ");
+
+        $refSec->append("\n  ", $example);
+
+        $refSec->appendChild(new DOMText("\n "));
+        return $refSec;
+    }
+
     /**
      * @param array<string, FuncInfo> $funcMap
      * @param array<string, FuncInfo> $aliasMap

From 83df95b718e84c81f7845d485f2ac54673b57fb5 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sat, 30 Sep 2023 19:34:31 +0100
Subject: [PATCH 08/15] [skip ci] extract common code

---
 build/gen_stub.php | 64 ++++++++++++++++------------------------------
 1 file changed, 22 insertions(+), 42 deletions(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index 1cf133401815f..62a8802019228 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1483,6 +1483,17 @@ private function getFlagsAsArginfoString(): string
         return $flags;
     }
 
+    private function generateRefSect1(DOMDocument $doc, string $role): DOMElement {
+        $refSec = $doc->createElement('refsect1');
+        $refSec->setAttribute('role', $role);
+        $refSec->append(
+            "\n  ",
+            $doc->createEntityReference('reftitle.' . $role),
+            "\n  "
+        );
+        return $refSec;
+    }
+
     /**
      * @param array<string, FuncInfo> $funcMap
      * @param array<string, FuncInfo> $aliasMap
@@ -1531,12 +1542,7 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         $refentry->append($refnamediv, $REFSEC1_SEPERATOR);
 
         /* Creation of <refsect1 role="description"> */
-        $descriptionRefSec = $doc->createElement('refsect1');
-        $descriptionRefSec->setAttribute('role', 'description');
-        $descriptionRefSec->appendChild(new DOMText("\n  "));
-        $refTitleDescription = $doc->createEntityReference('reftitle.description');
-        $descriptionRefSec->appendChild($refTitleDescription);
-        $descriptionRefSec->appendChild(new DOMText("\n  "));
+        $descriptionRefSec = $this->generateRefSect1($doc, 'description');
 
         $methodSynopsis = $this->getMethodSynopsisElement($funcMap, $aliasMap, $doc);
         if (!$methodSynopsis) {
@@ -1565,12 +1571,7 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         }
 
         /* Creation of <refsect1 role="errors"> */
-        $errorsRefSec = $doc->createElement('refsect1');
-        $errorsRefSec->setAttribute('role', 'errors');
-        $errorsRefSec->appendChild(new DOMText("\n  "));
-        $refTitleErrors = $doc->createEntityReference('reftitle.errors');
-        $errorsRefSec->appendChild($refTitleErrors);
-        $errorsRefSec->appendChild(new DOMText("\n  "));
+        $errorsRefSec = $this->generateRefSect1($doc, 'errors');
         $errorsDescriptionPara = $doc->createElement('para');
         $errorsDescriptionPara->appendChild(new DOMText("\n   When does this function issue E_* level errors, and/or throw exceptions.\n  "));
         $errorsRefSec->appendChild($errorsDescriptionPara);
@@ -1582,17 +1583,13 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         $changelogRefSec = $this->getChangelogSection($doc);
         $refentry->append($changelogRefSec, $REFSEC1_SEPERATOR);
 
-        // TODO Examples, and Notes sections
         $exampleRefSec = $this->getExampleSection($doc);
         $refentry->append($exampleRefSec, $REFSEC1_SEPERATOR);
 
+        // TODO Notes section?
+
         /* Creation of <refsect1 role="seealso"> */
-        $seeAlsoRefSec = $doc->createElement('refsect1');
-        $seeAlsoRefSec->setAttribute('role', 'seealso');
-        $seeAlsoRefSec->appendChild(new DOMText("\n  "));
-        $refTitleSeeAlso = $doc->createEntityReference('reftitle.seealso');
-        $seeAlsoRefSec->appendChild($refTitleSeeAlso);
-        $seeAlsoRefSec->appendChild(new DOMText("\n  "));
+        $seeAlsoRefSec = $this->generateRefSect1($doc, 'seealso');
 
         /* TODO Actually generate a markup for class names, functions and links?
   <simplelist>
@@ -1644,12 +1641,7 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
     }
 
     private function getParameterSection(DOMDocument $doc): DOMElement {
-        $parametersRefSec = $doc->createElement('refsect1');
-        $parametersRefSec->setAttribute('role', 'parameters');
-        $parametersRefSec->appendChild(new DOMText("\n  "));
-        $refTitle = $doc->createEntityReference('reftitle.parameters');
-        $parametersRefSec->appendChild($refTitle);
-        $parametersRefSec->appendChild(new DOMText("\n  "));
+        $parametersRefSec = $this->generateRefSect1($doc, 'parameters');
         if (empty($this->args)) {
             $noParamEntity = $doc->createEntityReference('no.function.parameters');
             $parametersRefSec->appendChild($noParamEntity);
@@ -1706,12 +1698,8 @@ private function getParameterSection(DOMDocument $doc): DOMElement {
     }
 
     private function getReturnValueSection(DOMDocument $doc): DOMElement {
-        $returnRefSec = $doc->createElement('refsect1');
-        $returnRefSec->setAttribute('role', 'returnvalues');
-        $returnRefSec->appendChild(new DOMText("\n  "));
-        $refTitle = $doc->createEntityReference('reftitle.returnvalues');
-        $returnRefSec->appendChild($refTitle);
-        $returnRefSec->appendChild(new DOMText("\n  "));
+        $returnRefSec = $this->generateRefSect1($doc, 'returnvalues');
+
         $returnDescriptionPara = $doc->createElement('para');
         $returnDescriptionPara->appendChild(new DOMText("\n   "));
 
@@ -1799,12 +1787,7 @@ private function generateDocbookInformalTable(
     }
 
     private function getChangelogSection(DOMDocument $doc): DOMElement {
-        $refSec = $doc->createElement('refsect1');
-        $refSec->setAttribute('role', 'changelog');
-        $refSec->appendChild(new DOMText("\n  "));
-        $refTitle = $doc->createEntityReference('reftitle.changelog');
-        $refSec->appendChild($refTitle);
-        $refSec->appendChild(new DOMText("\n  "));
+        $refSec = $this->generateRefSect1($doc, 'changelog');
         $headers = [
             $doc->createEntityReference('Version'),
             $doc->createEntityReference('Description'),
@@ -1821,10 +1804,7 @@ private function getChangelogSection(DOMDocument $doc): DOMElement {
     }
 
     private function getExampleSection(DOMDocument $doc): DOMElement {
-        $refSec = $doc->createElement('refsect1');
-        $refSec->setAttribute('role', 'examples');
-        $refTitle = $doc->createEntityReference('reftitle.examples');
-        $refSec->append("\n  ", $refTitle);
+        $refSec = $this->generateRefSect1($doc, 'examples');
 
         $example = $doc->createElement('example');
         $example->setAttribute('xml:id', 'func-or-method-name.example.basic');
@@ -1873,7 +1853,7 @@ private function getExampleSection(DOMDocument $doc): DOMElement {
         $example->append("\n   ", $screen);
         $example->append("\n  ");
 
-        $refSec->append("\n  ", $example);
+        $refSec->append($example);
 
         $refSec->appendChild(new DOMText("\n "));
         return $refSec;

From a69960ddba96657141c512c8e0dd3999d414bd36 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sat, 30 Sep 2023 19:55:59 +0100
Subject: [PATCH 09/15] Optimize call

We can just lowercase the result instead of doing each part before
---
 build/gen_stub.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index 62a8802019228..e34a911bb0cc8 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1109,7 +1109,7 @@ public function getMethodSynopsisFilename(): string
     {
         $parts = [...$this->className->getParts(), ltrim($this->methodName, '_')];
         /* File paths are in lowercase */
-        return implode('/', array_map('strtolower', $parts));
+        return strtolower(implode('/', $parts));
     }
 
     public function getNameForAttributes(): string {

From 81cea164d9d670cd113d6fde0a5540967ddc59e3 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sat, 30 Sep 2023 23:46:50 +0100
Subject: [PATCH 10/15] [skip ci] Do not generate identical IDs

---
 build/gen_stub.php | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index e34a911bb0cc8..e7cd67a6e0c9c 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1807,11 +1807,14 @@ private function getExampleSection(DOMDocument $doc): DOMElement {
         $refSec = $this->generateRefSect1($doc, 'examples');
 
         $example = $doc->createElement('example');
-        $example->setAttribute('xml:id', 'func-or-method-name.example.basic');
+        $fnName = $this->name->__toString();
+        $fnNameForId = strtolower($fnName);
+        $fnNameForId = str_replace(['_', '\\', '::'], ['-', '-', '.'], $fnNameForId);
+        $example->setAttribute('xml:id', $fnNameForId . '.example.basic');
 
         $title = $doc->createElement('title');
         $fn = $doc->createElement($this->isMethod() ? 'methodname' : 'function');
-        $fn->append($this->name->__toString());
+        $fn->append($fnName);
         $title->append($fn, ' example');
 
         $example->append("\n   ", $title);

From 10cd477d47de3e4a4e9198bdd6135924536795e4 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sat, 28 Oct 2023 13:51:32 +0100
Subject: [PATCH 11/15] [skip ci] Update return type
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Máté Kocsis <kocsismate@woohoolabs.com>
---
 build/gen_stub.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index e7cd67a6e0c9c..ab70326e66fe6 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1703,7 +1703,7 @@ private function getReturnValueSection(DOMDocument $doc): DOMElement {
         $returnDescriptionPara = $doc->createElement('para');
         $returnDescriptionPara->appendChild(new DOMText("\n   "));
 
-        $returnType = $this->return->type;
+        $returnType = $this->return->getMethodSynopsisType();
         if ($returnType === null) {
             $returnDescriptionPara->appendChild(new DOMText("Description"));
         } else if (count($returnType->types) === 1) {

From b2110d1246579267195c0c20e8f1428449c22640 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Sat, 28 Oct 2023 14:32:16 +0100
Subject: [PATCH 12/15] [skip ci] Reviw + notes section

---
 build/gen_stub.php | 93 ++++++++++++++++++++++++++++++++++++----------
 1 file changed, 73 insertions(+), 20 deletions(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index ab70326e66fe6..b01bfe5655186 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1572,8 +1572,18 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
 
         /* Creation of <refsect1 role="errors"> */
         $errorsRefSec = $this->generateRefSect1($doc, 'errors');
+        $errorsDescriptionParaConstantTag = $doc->createElement('constant');
+        $errorsDescriptionParaConstantTag->append("E_*");
+        $errorsDescriptionParaExceptionTag = $doc->createElement('exceptionname');
+        $errorsDescriptionParaExceptionTag->append("Exception");
         $errorsDescriptionPara = $doc->createElement('para');
-        $errorsDescriptionPara->appendChild(new DOMText("\n   When does this function issue E_* level errors, and/or throw exceptions.\n  "));
+        $errorsDescriptionPara->append(
+            "\n   When does this function issue ",
+            $errorsDescriptionParaConstantTag,
+            " level errors, and/or throw ",
+            $errorsDescriptionParaExceptionTag,
+            "s.\n  "
+        );
         $errorsRefSec->appendChild($errorsDescriptionPara);
         $errorsRefSec->appendChild(new DOMText("\n "));
 
@@ -1583,28 +1593,51 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         $changelogRefSec = $this->getChangelogSection($doc);
         $refentry->append($changelogRefSec, $REFSEC1_SEPERATOR);
 
-        $exampleRefSec = $this->getExampleSection($doc);
+        $exampleRefSec = $this->getExampleSection($doc, $id);
         $refentry->append($exampleRefSec, $REFSEC1_SEPERATOR);
 
-        // TODO Notes section?
+        /* Creation of <refsect1 role="notes"> */
+        $notesRefSec = $this->generateRefSect1($doc, 'notes');
+
+        $noteTagSimara = $doc->createElement('simpara');
+        $noteTagSimara->append(
+            "\n    Any notes that don't fit anywhere else should go here.\n   "
+        );
+        $noteTag = $doc->createElement('note');
+        $noteTag->append("\n   ", $noteTagSimara, "\n  ");
+        $notesRefSec->append($noteTag, "\n ");
+
+        $refentry->append($notesRefSec, $REFSEC1_SEPERATOR);
 
         /* Creation of <refsect1 role="seealso"> */
         $seeAlsoRefSec = $this->generateRefSect1($doc, 'seealso');
 
-        /* TODO Actually generate a markup for class names, functions and links?
-  <simplelist>
-   <member><methodname>ClassName::otherMethodName</methodname></member>
-   <member><function>some_function</function></member>
-   <member>The <link linkend="something">something appendix</link></member>
-  </simplelist>
-         */
-        $seeAlsoMember = $doc->createElement('member');
-        $seeAlsoMember->appendChild(new DOMText("Method name, function, or link to reference"));
+        $seeAlsoMemberClassMethod = $doc->createElement('member');
+        $seeAlsoMemberClassMethodTag = $doc->createElement('methodname');
+        $seeAlsoMemberClassMethodTag->appendChild(new DOMText("ClassName::otherMethodName"));
+        $seeAlsoMemberClassMethod->appendChild($seeAlsoMemberClassMethodTag);
+
+        $seeAlsoMemberFunction = $doc->createElement('member');
+        $seeAlsoMemberFunctionTag = $doc->createElement('function');
+        $seeAlsoMemberFunctionTag->appendChild(new DOMText("some_function"));
+        $seeAlsoMemberFunction->appendChild($seeAlsoMemberFunctionTag);
+
+        $seeAlsoMemberLink = $doc->createElement('member');
+        $seeAlsoMemberLinkTag = $doc->createElement('link');
+        $seeAlsoMemberLinkTag->setAttribute('linkend', 'some.id.chunk.to.link');
+        $seeAlsoMemberLinkTag->appendChild(new DOMText("something appendix"));
+        $seeAlsoMemberLink->appendChild($seeAlsoMemberLinkTag);
 
         $seeAlsoList = $doc->createElement('simplelist');
-        $seeAlsoList->appendChild(new DOMText("\n   "));
-        $seeAlsoList->appendChild($seeAlsoMember);
-        $seeAlsoList->appendChild(new DOMText("\n  "));
+        $seeAlsoList->append(
+            "\n   ",
+            $seeAlsoMemberClassMethod,
+            "\n   ",
+            $seeAlsoMemberFunction,
+            "\n   ",
+            $seeAlsoMemberLink,
+            "\n  "
+        );
 
         $seeAlsoRefSec->appendChild($seeAlsoList);
         $seeAlsoRefSec->appendChild(new DOMText("\n "));
@@ -1709,12 +1742,28 @@ private function getReturnValueSection(DOMDocument $doc): DOMElement {
         } else if (count($returnType->types) === 1) {
             $type = $returnType->types[0];
             $name = $type->name;
+            /*
             $descriptionNode = match ($name) {
                 'void' => $doc->createEntityReference('return.void'),
                 'true' => $doc->createEntityReference('return.true.always'),
                 'bool' => $doc->createEntityReference('return.success'),
                 default => new DOMText("Description"),
             };
+            */
+            switch ($name) {
+                case 'void':
+                    $descriptionNode = $doc->createEntityReference('return.void');
+                    break;
+                case 'true':
+                    $descriptionNode = $doc->createEntityReference('return.true.always');
+                    break;
+                case 'bool':
+                    $descriptionNode = $doc->createEntityReference('return.success');
+                    break;
+                default:
+                    $descriptionNode = new DOMText("Description");
+                    break;
+            }
             $returnDescriptionPara->appendChild($descriptionNode);
         } else {
             $returnDescriptionPara->appendChild(new DOMText("Description"));
@@ -1796,21 +1845,25 @@ private function getChangelogSection(DOMDocument $doc): DOMElement {
             new DOMText('8.X.0'),
             new DOMText("\n       Description\n      "),
         ]];
-        $table = $this->generateDocbookInformalTable($doc, indent: 2, columns: 2, headers: $headers, rows: $rows);
+        $table = $this->generateDocbookInformalTable(
+            $doc,
+            /* indent: */ 2,
+            /* columns: */ 2,
+            /* headers: */ $headers,
+            /* rows: */ $rows
+        );
         $refSec->appendChild($table);
 
         $refSec->appendChild(new DOMText("\n "));
         return $refSec;
     }
 
-    private function getExampleSection(DOMDocument $doc): DOMElement {
+    private function getExampleSection(DOMDocument $doc, string $id): DOMElement {
         $refSec = $this->generateRefSect1($doc, 'examples');
 
         $example = $doc->createElement('example');
         $fnName = $this->name->__toString();
-        $fnNameForId = strtolower($fnName);
-        $fnNameForId = str_replace(['_', '\\', '::'], ['-', '-', '.'], $fnNameForId);
-        $example->setAttribute('xml:id', $fnNameForId . '.example.basic');
+        $example->setAttribute('xml:id', $id . '.example.basic');
 
         $title = $doc->createElement('title');
         $fn = $doc->createElement($this->isMethod() ? 'methodname' : 'function');

From 6844250e1ec1e5c0ed94dcc76a2912c7e2b4e5e8 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Tue, 31 Oct 2023 11:19:37 +0000
Subject: [PATCH 13/15] Remove comment, use append() method more

---
 build/gen_stub.php | 111 ++++++++++++++++++++++++---------------------
 1 file changed, 60 insertions(+), 51 deletions(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index b01bfe5655186..2c5d204a6f39e 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -1554,7 +1554,7 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         $descriptionRefSec->appendChild($undocumentedEntity);
         $descriptionRefSec->appendChild(new DOMText("\n  "));
         $returnDescriptionPara = $doc->createElement('para');
-        $returnDescriptionPara->appendChild(new DOMText("\n   Description\n  "));
+        $returnDescriptionPara->appendChild(new DOMText("\n   Description.\n  "));
         $descriptionRefSec->appendChild($returnDescriptionPara);
 
         $descriptionRefSec->appendChild(new DOMText("\n "));
@@ -1573,14 +1573,14 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         /* Creation of <refsect1 role="errors"> */
         $errorsRefSec = $this->generateRefSect1($doc, 'errors');
         $errorsDescriptionParaConstantTag = $doc->createElement('constant');
-        $errorsDescriptionParaConstantTag->append("E_*");
+        $errorsDescriptionParaConstantTag->append('E_*');
         $errorsDescriptionParaExceptionTag = $doc->createElement('exceptionname');
-        $errorsDescriptionParaExceptionTag->append("Exception");
+        $errorsDescriptionParaExceptionTag->append('Exception');
         $errorsDescriptionPara = $doc->createElement('para');
         $errorsDescriptionPara->append(
             "\n   When does this function issue ",
             $errorsDescriptionParaConstantTag,
-            " level errors, and/or throw ",
+            " level errors,\n   and/or throw ",
             $errorsDescriptionParaExceptionTag,
             "s.\n  "
         );
@@ -1625,7 +1625,7 @@ public function getMethodSynopsisDocument(array $funcMap, array $aliasMap): ?str
         $seeAlsoMemberLink = $doc->createElement('member');
         $seeAlsoMemberLinkTag = $doc->createElement('link');
         $seeAlsoMemberLinkTag->setAttribute('linkend', 'some.id.chunk.to.link');
-        $seeAlsoMemberLinkTag->appendChild(new DOMText("something appendix"));
+        $seeAlsoMemberLinkTag->appendChild(new DOMText('something appendix'));
         $seeAlsoMemberLink->appendChild($seeAlsoMemberLinkTag);
 
         $seeAlsoList = $doc->createElement('simplelist');
@@ -1702,23 +1702,28 @@ private function getParameterSection(DOMDocument $doc): DOMElement {
                 $parameterTerm = $doc->createElement('term');
                 $parameterTerm->appendChild($parameter);
 
-                $parameterEntry = $doc->createElement('varlistentry');
-                $parameterEntry->appendChild(new DOMText("\n     "));
-                $parameterEntry->appendChild($parameterTerm);
-                $parameterEntry->appendChild(new DOMText("\n     "));
-
                 $listItemPara = $doc->createElement('para');
-                $listItemPara->appendChild(new DOMText("\n       "));
-                $listItemPara->appendChild(new DOMText("Description."));
-                $listItemPara->appendChild(new DOMText("\n      "));
+                $listItemPara->append(
+                    "\n       ",
+                    "Description.",
+                    "\n      ",
+                );
 
                 $parameterEntryListItem = $doc->createElement('listitem');
-                $parameterEntryListItem->appendChild(new DOMText("\n      "));
-                $parameterEntryListItem->appendChild($listItemPara);
-                $parameterEntryListItem->appendChild(new DOMText("\n     "));
+                $parameterEntryListItem->append(
+                    "\n      ",
+                    $listItemPara,
+                    "\n     ",
+                );
 
-                $parameterEntry->appendChild($parameterEntryListItem);
-                $parameterEntry->appendChild(new DOMText("\n    "));
+                $parameterEntry = $doc->createElement('varlistentry');
+                $parameterEntry->append(
+                    "\n     ",
+                    $parameterTerm,
+                    "\n     ",
+                    $parameterEntryListItem,
+                    "\n    ",
+                );
 
                 $parametersList->appendChild(new DOMText("\n    "));
                 $parametersList->appendChild($parameterEntry);
@@ -1738,18 +1743,11 @@ private function getReturnValueSection(DOMDocument $doc): DOMElement {
 
         $returnType = $this->return->getMethodSynopsisType();
         if ($returnType === null) {
-            $returnDescriptionPara->appendChild(new DOMText("Description"));
+            $returnDescriptionPara->appendChild(new DOMText("Description."));
         } else if (count($returnType->types) === 1) {
             $type = $returnType->types[0];
             $name = $type->name;
-            /*
-            $descriptionNode = match ($name) {
-                'void' => $doc->createEntityReference('return.void'),
-                'true' => $doc->createEntityReference('return.true.always'),
-                'bool' => $doc->createEntityReference('return.success'),
-                default => new DOMText("Description"),
-            };
-            */
+
             switch ($name) {
                 case 'void':
                     $descriptionNode = $doc->createEntityReference('return.void');
@@ -1761,12 +1759,12 @@ private function getReturnValueSection(DOMDocument $doc): DOMElement {
                     $descriptionNode = $doc->createEntityReference('return.success');
                     break;
                 default:
-                    $descriptionNode = new DOMText("Description");
+                    $descriptionNode = new DOMText("Description.");
                     break;
             }
             $returnDescriptionPara->appendChild($descriptionNode);
         } else {
-            $returnDescriptionPara->appendChild(new DOMText("Description"));
+            $returnDescriptionPara->appendChild(new DOMText("Description."));
         }
         $returnDescriptionPara->appendChild(new DOMText("\n  "));
         $returnRefSec->appendChild($returnDescriptionPara);
@@ -1792,15 +1790,16 @@ private function generateDocbookInformalTable(
             $headerEntry = $doc->createElement('entry');
             $headerEntry->appendChild($header);
 
-            $headerRow->appendChild(new DOMText("\n$strIndent    "));
-            $headerRow->appendChild($headerEntry);
+            $headerRow->append("\n$strIndent    ", $headerEntry);
         }
-        $headerRow->appendChild(new DOMText("\n$strIndent   "));
+        $headerRow->append("\n$strIndent   ");
 
         $thead = $doc->createElement('thead');
-        $thead->appendChild(new DOMText("\n$strIndent   "));
-        $thead->appendChild($headerRow);
-        $thead->appendChild(new DOMText("\n$strIndent  "));
+        $thead->append(
+            "\n$strIndent   ",
+            $headerRow,
+            "\n$strIndent  ",
+        );
 
         $tbody = $doc->createElement('tbody');
         foreach ($rows as $row) {
@@ -1814,23 +1813,29 @@ private function generateDocbookInformalTable(
             }
             $bodyRow->appendChild(new DOMText("\n$strIndent   "));
 
-            $tbody->appendChild(new DOMText("\n$strIndent   "));
-            $tbody->appendChild($bodyRow);
-            $tbody->appendChild(new DOMText("\n$strIndent  "));
+            $tbody->append(
+                "\n$strIndent   ",
+                $bodyRow,
+                "\n$strIndent  ",
+            );
         }
 
         $tgroup = $doc->createElement('tgroup');
         $tgroup->setAttribute('cols', (string) $columns);
-        $tgroup->appendChild(new DOMText("\n$strIndent  "));
-        $tgroup->appendChild($thead);
-        $tgroup->appendChild(new DOMText("\n$strIndent  "));
-        $tgroup->appendChild($tbody);
-        $tgroup->appendChild(new DOMText("\n$strIndent "));
+        $tgroup->append(
+            "\n$strIndent  ",
+            $thead,
+            "\n$strIndent  ",
+            $tbody,
+            "\n$strIndent ",
+        );
 
         $table = $doc->createElement('informaltable');
-        $table->appendChild(new DOMText("\n$strIndent "));
-        $table->appendChild($tgroup);
-        $table->appendChild(new DOMText("\n$strIndent"));
+        $table->append(
+            "\n$strIndent ",
+            $tgroup,
+            "\n$strIndent",
+        );
 
         return $table;
     }
@@ -1906,12 +1911,16 @@ private function getExampleSection(DOMDocument $doc, string $id): DOMElement {
         $screen->appendChild($output);
         $screen->append("\n   ");
 
-        $example->append("\n   ", $screen);
-        $example->append("\n  ");
-
-        $refSec->append($example);
+        $example->append(
+            "\n   ",
+            $screen,
+            "\n  ",
+        );
 
-        $refSec->appendChild(new DOMText("\n "));
+        $refSec->append(
+            $example,
+            "\n ",
+        );
         return $refSec;
     }
 

From e22e0e6ab9416e79c9e2cbd4f29a7c18c9f47d69 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Tue, 31 Oct 2023 11:57:02 +0000
Subject: [PATCH 14/15] [skip ci] use new

---
 build/gen_stub.php | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index 2c5d204a6f39e..2bd814f3ce882 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -5786,12 +5786,7 @@ function(?ArgInfo $aliasArg, ?ArgInfo $aliasedArg) use ($aliasFunc, $aliasedFunc
 }
 
 if ($generateMethodSynopses) {
-    // Use the manual as target if we are targeting a specific extension
-    if (str_contains($manualTarget, 'reference')) {
-        $methodSynopsesDirectory = $manualTarget;
-    } else {
-        $methodSynopsesDirectory = getcwd() . "/methodsynopses";
-    }
+    $methodSynopsesDirectory = array_pop($locations);
 
     $methodSynopses = generateMethodSynopses($funcMap, $aliasMap);
     if (!empty($methodSynopses)) {

From 7fb388d1130cd8f15496c7c8b10d8dfe084b7d43 Mon Sep 17 00:00:00 2001
From: Gina Peter Banyard <girgias@php.net>
Date: Tue, 31 Oct 2023 16:15:36 +0000
Subject: [PATCH 15/15] [skip ci] Update gen_stub for manual target

---
 build/gen_stub.php | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/build/gen_stub.php b/build/gen_stub.php
index 2bd814f3ce882..2ee52a814435c 100755
--- a/build/gen_stub.php
+++ b/build/gen_stub.php
@@ -5580,6 +5580,9 @@ function initPhpParser() {
 if ($replaceClassSynopses && $locationCount < 2) {
     die("At least one source stub path and a target manual directory has to be provided:\n./build/gen_stub.php --replace-classsynopses ./ ../doc-en/\n");
 }
+if ($generateMethodSynopses && $locationCount < 2) {
+    die("At least one source stub path and a target manual directory has to be provided:\n./build/gen_stub.php --generate-methodsynopses ./ ../doc-en/\n");
+}
 if ($replaceMethodSynopses && $locationCount < 2) {
     die("At least one source stub path and a target manual directory has to be provided:\n./build/gen_stub.php --replace-methodsynopses ./ ../doc-en/\n");
 }
@@ -5587,7 +5590,7 @@ function initPhpParser() {
     die("At least one source stub path and a target manual directory has to be provided:\n./build/gen_stub.php --verify-manual ./ ../doc-en/\n");
 }
 $manualTarget = null;
-if ($replacePredefinedConstants || $replaceClassSynopses || $replaceMethodSynopses || $verifyManual) {
+if ($replacePredefinedConstants || $replaceClassSynopses || $generateMethodSynopses || $replaceMethodSynopses || $verifyManual) {
     $manualTarget = array_pop($locations);
 }
 if ($locations === []) {
@@ -5786,19 +5789,15 @@ function(?ArgInfo $aliasArg, ?ArgInfo $aliasedArg) use ($aliasFunc, $aliasedFunc
 }
 
 if ($generateMethodSynopses) {
-    $methodSynopsesDirectory = array_pop($locations);
-
     $methodSynopses = generateMethodSynopses($funcMap, $aliasMap);
-    if (!empty($methodSynopses)) {
-        if (!file_exists($methodSynopsesDirectory)) {
-            mkdir($methodSynopsesDirectory);
-        }
+    if (!file_exists($manualTarget)) {
+        mkdir($manualTarget);
+    }
 
-        foreach ($methodSynopses as $filename => $content) {
-            if (!file_exists("$methodSynopsesDirectory/$filename")) {
-                if (file_put_contents("$methodSynopsesDirectory/$filename", $content)) {
-                    echo "Saved $filename\n";
-                }
+    foreach ($methodSynopses as $filename => $content) {
+        if (!file_exists("$manualTarget/$filename")) {
+            if (file_put_contents("$manualTarget/$filename", $content)) {
+                echo "Saved $filename\n";
             }
         }
     }