Add basic Attribute linking (#127)

This adds support for 'known' attributes on method and function parameters. 'Known' in this context means an attribute that has been declared in the documentation with an ID in the `class.attribute_name` format (all current predefined attributes are supported). Current limitations are: - No support for namespaced attributes - No support for attributes on a return type Co-authored-by: haszi <[email protected]>
php · May 20, 2024 · dda2c63 · dda2c63
1 parent b535eeb
commit dda2c63
Show file tree

Hide file tree

Showing 3 changed files with 123 additions and 1 deletion.
diff --git a/phpdotnet/phd/Package/Generic/XHTML.php b/phpdotnet/phd/Package/Generic/XHTML.php
@@ -145,7 +145,7 @@ abstract class Package_Generic_XHTML extends Format_Abstract_XHTML {
         'methodsynopsis'        => 'format_methodsynopsis',
         'methodname'            => 'format_methodname',
         'member'                => 'format_member',
-        'modifier'              => 'span',
+        'modifier'              => 'format_modifier',
         'note'                  => 'format_note',
         'orgname'               => 'span',
         'othercredit'           => 'format_div',
@@ -393,6 +393,8 @@ abstract class Package_Generic_XHTML extends Format_Abstract_XHTML {
         'modifier'             => array(
             /* DEFAULT */         false,
             'fieldsynopsis'    => 'format_fieldsynopsis_modifier_text',
+            'methodparam'      => 'format_modifier_text',
+            'methodsynopsis'   => 'format_modifier_text',
         ),
         /** Those are used to retrieve the class/interface name to be able to remove it from method names */
         'classname' => [
@@ -1217,6 +1219,31 @@ public function format_fieldsynopsis_modifier_text($value, $tag) {
         return $this->TEXT($value);
     }
 
+    public function format_modifier($open, $name, $attrs, $props) {
+        if ($open) {
+            if (isset($attrs[Reader::XMLNS_DOCBOOK]["role"])) {
+                $this->pushRole($attrs[Reader::XMLNS_DOCBOOK]["role"]);
+                return '<span class="' . $this->getRole() . '">';
+            }
+            return '<span class="modifier">';
+        }
+        if (isset($attrs[Reader::XMLNS_DOCBOOK]["role"])) {
+            $this->popRole();
+        }
+        return '</span>';
+    }
+
+    public function format_modifier_text($value, $tag) {
+        if ($this->getRole() === "attribute") {
+            $attribute = trim(strtolower($value), "#[]\\");
+            $href = Format::getFilename("class.$attribute");
+            if ($href) {
+                return '<a href="' . $href . $this->getExt() . '">' .$value. '</a> ';
+            }
+        }
+        return false;
+    }
+
     public function format_methodsynopsis($open, $name, $attrs, $props) {
         if ($open) {
 

diff --git a/tests/package/generic/attribute_formatting_001.phpt b/tests/package/generic/attribute_formatting_001.phpt
@@ -0,0 +1,60 @@
+--TEST--
+Attribute formatting 001
+--FILE--
+<?php
+namespace phpdotnet\phd;
+
+require_once __DIR__ . "/../../setup.php";
+
+$xml_file = __DIR__ . "/data/attribute_formatting_001.xml";
+
+Config::init(["xml_file" => $xml_file]);
+
+$format = new TestGenericChunkedXHTML;
+
+$format->SQLiteIndex(
+    null, // $context,
+    null, // $index,
+    "class.knownattribute", // $id,
+    "file.knownattribute.is.in", // $filename,
+    "", // $parent,
+    "", // $sdesc,
+    "", // $ldesc,
+    "", // $element,
+    "", // $previous,
+    "", // $next,
+    0, // $chunk
+);
+
+$render = new TestRender(new Reader, new Config, $format);
+
+$render->run();
+?>
+--EXPECT--
+Filename: attribute-formatting.html
+Content:
+<div id="attribute-formatting" class="chapter">
+ <div class="section">
+  <p class="para">1. Class methodparameter with unknown attribute</p>
+  <div class="constructorsynopsis dc-description"><span class="modifier">public</span>  <span class="methodname">mysqli::__construct</span>(<span class="methodparam"><span class="attribute">#[\UnknownAttribute]</span><span class="type"><span class="type">string</span><span class="type">null</span></span> <code class="parameter">$password</code><span class="initializer"> = <span class="type">null</span></span></span>)</div>
+
+ </div>
+
+ <div class="section">
+  <p class="para">2. Class methodparameter with known attribute</p>
+  <div class="constructorsynopsis dc-description"><span class="modifier">public</span>  <span class="methodname">mysqli::__construct</span>(<span class="methodparam"><span class="attribute"><a href="file.knownattribute.is.in.html">#[\KnownAttribute]</a> </span><span class="type"><span class="type">string</span><span class="type">null</span></span> <code class="parameter">$password</code><span class="initializer"> = <span class="type">null</span></span></span>)</div>
+
+ </div>
+
+ <div class="section">
+  <p class="para">3. Function parameter with unknown attribute</p>
+  <div class="methodsynopsis dc-description"><span class="type">bool</span> <span class="methodname">password_verify</span><span class="attribute">#[\UnknownAttribute]</span>(<span class="methodparam"><span class="type">string</span> <code class="parameter">$password</code></span>, <span class="methodparam"><span class="type">string</span> <code class="parameter">$hash</code></span>)</div>
+
+ </div>
+
+ <div class="section">
+  <p class="para">4. Function parameter with known attribute</p>
+  <div class="methodsynopsis dc-description"><span class="type">bool</span> <span class="methodname">password_verify</span><span class="attribute"><a href="file.knownattribute.is.in.html">#[\KnownAttribute]</a> </span>(<span class="methodparam"><span class="type">string</span> <code class="parameter">$password</code></span>, <span class="methodparam"><span class="type">string</span> <code class="parameter">$hash</code></span>)</div>
+
+ </div>
+</div>
diff --git a/tests/package/generic/data/attribute_formatting_001.xml b/tests/package/generic/data/attribute_formatting_001.xml
@@ -0,0 +1,35 @@
+<chapter xml:id="attribute-formatting">
+ <section>
+  <para>1. Class methodparameter with unknown attribute</para>
+  <constructorsynopsis role="mysqli">
+   <modifier>public</modifier> <methodname>mysqli::__construct</methodname>
+   <methodparam><modifier role="attribute">#[\UnknownAttribute]</modifier><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter><initializer><type>null</type></initializer></methodparam>
+  </constructorsynopsis>
+ </section>
+
+ <section>
+  <para>2. Class methodparameter with known attribute</para>
+  <constructorsynopsis role="mysqli">
+   <modifier>public</modifier> <methodname>mysqli::__construct</methodname>
+   <methodparam><modifier role="attribute">#[\KnownAttribute]</modifier><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter><initializer><type>null</type></initializer></methodparam>
+  </constructorsynopsis>
+ </section>
+
+ <section>
+  <para>3. Function parameter with unknown attribute</para>
+  <methodsynopsis>
+   <type>bool</type><methodname>password_verify</methodname>
+   <modifier role="attribute">#[\UnknownAttribute]</modifier><methodparam><type>string</type><parameter>password</parameter></methodparam>
+   <methodparam><type>string</type><parameter>hash</parameter></methodparam>
+  </methodsynopsis>
+ </section>
+
+ <section>
+  <para>4. Function parameter with known attribute</para>
+  <methodsynopsis>
+   <type>bool</type><methodname>password_verify</methodname>
+   <modifier role="attribute">#[\KnownAttribute]</modifier><methodparam><type>string</type><parameter>password</parameter></methodparam>
+   <methodparam><type>string</type><parameter>hash</parameter></methodparam>
+  </methodsynopsis>
+ </section>
+</chapter>