Make the usage of the role attribute more clear (#9901)

Currently, the role attribute is mainly used to differentiate OO and procedural "aliases" when they are documented on the same page (e.g. https://www.php.net/manual/en/datetime.diff.php). However, these function-method counterparts are not always aliases in fact according to the stubs (#9491). That's why sometimes the usage of the role attribute is ambiguous, thus syncing the manual with the stubs results in false positive diffs.

This change fixes the problem by a very obtrusive way: by changing the value of all role="oop" attributes to the actual class name, like role="DateTime", and by getting rid of all role="procedural" attributes as they became unnecessary. This way, class synopsis pages can clearly reference methods, and skip functions. Additionally, gen_stub.php will be able to generate the correct methodsynopsis role even though a single page describes multiple methods, like `DateTime/DateTimeImmutable/DateTimeInterface::diff()`.

Author: kocsismate

build/gen_stub.php

@@ -1487,14 +1487,10 @@ public function getMethodSynopsisElement(array $funcMap, array $aliasMap, DOMDoc
 
         $methodSynopsis = $doc->createElement($synopsisType);
 
-        $aliasedFunc = $this->aliasType === "alias" && isset($funcMap[$this->alias->__toString()]) ? $funcMap[$this->alias->__toString()] : null;
-        $aliasFunc = $aliasMap[$this->name->__toString()] ?? null;
-
-        if (($this->aliasType === "alias" && $aliasedFunc !== null && $aliasedFunc->isMethod() !== $this->isMethod()) ||
-            ($aliasFunc !== null && $aliasFunc->isMethod() !== $this->isMethod())
-        ) {
+        if ($this->isMethod()) {
+            assert($this->name instanceof MethodName);
             $role = $doc->createAttribute("role");
-            $role->value = $this->isMethod() ? "oop" : "procedural";
+            $role->value = $this->name->className->__toString();
             $methodSynopsis->appendChild($role);
         }
 
@@ -2772,7 +2768,7 @@ public function getClassSynopsisElement(DOMDocument $doc, array $classMap, itera
                 $classSynopsis->appendChild(new DOMText("\n    "));
                 $includeElement = $this->createIncludeElement(
                     $doc,
-                    "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$classReference')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[not(@role='procedural')])"
+                    "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$classReference')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='$this->name'])"
                 );
                 $classSynopsis->appendChild($includeElement);
             }
@@ -2781,7 +2777,7 @@ public function getClassSynopsisElement(DOMDocument $doc, array $classMap, itera
                 $classSynopsis->appendChild(new DOMText("\n    "));
                 $includeElement = $this->createIncludeElement(
                     $doc,
-                    "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$classReference')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])"
+                    "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$classReference')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='$this->name'])"
                 );
                 $classSynopsis->appendChild($includeElement);
             }
@@ -2790,7 +2786,7 @@ public function getClassSynopsisElement(DOMDocument $doc, array $classMap, itera
                 $classSynopsis->appendChild(new DOMText("\n    "));
                 $includeElement = $this->createIncludeElement(
                     $doc,
-                    "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$classReference')/db:refentry/db:refsect1[@role='description']/descendant::db:destructorsynopsis[not(@role='procedural')])"
+                    "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$classReference')/db:refentry/db:refsect1[@role='description']/descendant::db:destructorsynopsis[@role='$this->name'])"
                 );
                 $classSynopsis->appendChild($includeElement);
             }
@@ -2807,7 +2803,7 @@ public function getClassSynopsisElement(DOMDocument $doc, array $classMap, itera
                 $parentReference = self::getClassSynopsisReference($parent);
                 $includeElement = $this->createIncludeElement(
                     $doc,
-                    "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$parentReference')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])"
+                    "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$parentReference')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='$parent')])"
                 );
                 $classSynopsis->appendChild($includeElement);
             }