Skip to content

Fix FQN class, method, property and constant linking #185

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jan 5, 2025
Merged

Fix FQN class, method, property and constant linking #185

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
80c2cd3
Fix FQN class and method linking
Jan 1, 2025
d82d265
Fix Config property assignment
Jan 1, 2025
70253bf
Add method for normalizing FQN
Jan 5, 2025
bbdf752
Add FQN normalization to properties
Jan 5, 2025
30399ed
Add FQN normalization to constants
Jan 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions phpdotnet/phd/Package/Generic/XHTML.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1811,7 +1811,7 @@ private function convertConstantNameToId(string $constantName): string {
$tempLinkValue = str_replace(
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In a future version, move all transformations inside the normalize function (trim, replace), to make understanding the code easier.

array("\\", "_"),
array("-", "-"),
strtolower(trim($constantName, "_"))
trim($this->normalizeFQN($constantName), "_")
);

if (str_contains($constantName, '::')) {
Expand Down Expand Up @@ -1855,7 +1855,7 @@ public function format_property_text($value, $tag) {
$tempLinkValue = str_replace(
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The replace list here differs from other point. Maybe there is necessary two normalize functions, or if the difference is accidental, to test what list of substitutions is the correct.

["\\", "_", "$"],
["-", "-", ""],
strtolower(trim($value, "_"))
trim($this->normalizeFQN($value), "_")
);

list($extensionAndClass, $property) = explode("::", $tempLinkValue);
Expand All @@ -1870,6 +1870,10 @@ public function format_property_text($value, $tag) {
return '<a href="' . $link . '">' . $value . '</a>';
}

protected function normalizeFQN(string $fqn): string {
return \ltrim(\strtolower($fqn), "\\");
}

public function admonition_title($title, $lang)
{
return '<strong class="' .(strtolower($title)). '">' .($this->autogen($title, $lang)). '</strong>';
Expand Down
8 changes: 4 additions & 4 deletions phpdotnet/phd/Package/PHP/XHTML.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -666,7 +666,7 @@ public function format_type_methodparam_text($type, $tagname) {
}

public function format_type_text($type, $tagname) {
$t = strtr(strtolower($type), ["_" => "-", "\\" => "-"]);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note how these substations lists are copied everywhere.

$t = strtr($this->normalizeFQN($type), ["_" => "-", "\\" => "-"]);
$fragment = "";

switch($t) {
Expand Down Expand Up @@ -714,7 +714,7 @@ public function format_type_text($type, $tagname) {
return false;
}

$classNames = ($type === "?") ? ($tagname . ' null') : ($tagname . ' ' . $type);
$classNames = ($type === "?") ? ($tagname . ' null') : ($tagname . ' ' . ltrim($type, "\\"));
if ($href && $this->chunked) {
return '<a href="' .$href. $this->getExt().($fragment ? "#$fragment" : ""). '" class="' . $classNames . '">' .$type. '</a>';
}
Expand Down Expand Up @@ -837,7 +837,7 @@ public function format_function_text($value, $tag, $display_value = null) {
if (isset($non_functions[$value])) {
$filename = "function." . str_replace("_", "-", $value);
} else {
$ref = strtolower($value);
$ref = $this->normalizeFQN($value);
$filename = $this->getRefnameLink($ref);
}
if ($filename !== null) {
Expand Down Expand Up @@ -880,7 +880,7 @@ public function format_classsynopsis_oo_name_text($value, $tag) {
}

public function format_classname_text($value, $tag) {
if (($filename = $this->getClassnameLink(strtolower($value))) !== null && $this->cchunk["class_name_ref"] !== strtolower($value)) {
if (($filename = $this->getClassnameLink($this->normalizeFQN($value))) !== null && $this->cchunk["class_name_ref"] !== strtolower($value)) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is somewhat unrelated, but in a future version, first test if getClassnameLink() with fails with raw string, and then test again with plain \trim(). In this case, generate the link as usual but generate an warning, as this a source error (unexpected whitespace around type/constante/etc tags).

$href = $this->chunked ? $filename.$this->ext : "#$filename";
return '<a href="'.$href. '" class="' .$tag. '">' .$value. '</a>';
}
Expand Down
77 changes: 77 additions & 0 deletions tests/package/php/class_and_method_link_rendering_001.phpt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
--TEST--
Class and method link rendering 001
--FILE--
<?php
namespace phpdotnet\phd;

require_once __DIR__ . "/../../setup.php";

$config->xmlFile = __DIR__ . "/data/class_and_method_link_rendering_001.xml";

$indices = [
[
"docbook_id" => "class.extension-namespace-existing-class",
"filename" => "extensionname.classpage",
"element" => "phpdoc:classref",
],
[
"docbook_id" => "extension-namespace-classname.existingmethodname",
"filename" => "extension-namespace-classname.methodpage",
],
];

$format = new TestPHPChunkedXHTML($config, $outputHandler);

foreach ($indices as $index) {
$format->SQLiteIndex(
null, // $context,
null, // $index,
$index["docbook_id"] ?? "", // $id,
$index["filename"] ?? "", // $filename,
$index["parent_id"] ?? "", // $parent,
$index["sdesc"] ?? "", // $sdesc,
$index["ldesc"] ?? "", // $ldesc,
$index["element"] ?? "", // $element,
$index["previous"] ?? "", // $previous,
$index["next"] ?? "", // $next,
$index["chunk"] ?? 0, // $chunk
);
}

$format->addClassname("class.extension-namespace-existing-class", "extension\\namespace\\existing_class");
$format->addRefname("extension-namespace-classname.existingmethodname", "extension\\namespace\\classname::existingmethodname");

$render = new TestRender(new Reader($outputHandler), $config, $format);

$render->run();
?>
--EXPECTF--
Filename: class_and_method_link_rendering.html
Content:
<div id="class_and_method_link_rendering" class="chapter">

<div class="section">
<p class="para">1. Class linking</p>
<span class="classname"><a href="class.extension-namespace-existing-class.html" class="classname">Extension\Namespace\Existing_Class</a></span>
<span class="classname"><a href="class.extension-namespace-existing-class.html" class="classname">\Extension\Namespace\Existing_Class</a></span>
</div>

<div class="section">
<p class="para">2. Method/Function linking</p>
<span class="methodname"><a href="extension-namespace-classname.existingmethodname.html" class="methodname">Extension\Namespace\Classname::existingMethodName()</a></span>
<span class="methodname"><a href="extension-namespace-classname.existingmethodname.html" class="methodname">\Extension\Namespace\Classname::existingMethodName()</a></span>
</div>

<div class="section">
<p class="para">3. Class linking (non-FQN) in method/function parameter and return type</p>
<div class="methodsynopsis dc-description"><span class="methodname"><strong>method_name</strong></span>(<span class="methodparam"><span class="type"><a href="extensionname.classpage.html" class="type Extension\Namespace\Existing_Class">Extension\Namespace\Existing_Class</a></span> <code class="parameter">$paramName</code></span>): <span class="type"><a href="extensionname.classpage.html" class="type Extension\Namespace\Existing_Class">Extension\Namespace\Existing_Class</a></span></div>

</div>

<div class="section">
<p class="para">4. Class linking (FQN) in method/function parameter and return type</p>
<div class="methodsynopsis dc-description"><span class="methodname"><strong>method_name</strong></span>(<span class="methodparam"><span class="type"><a href="extensionname.classpage.html" class="type Extension\Namespace\Existing_Class">\Extension\Namespace\Existing_Class</a></span> <code class="parameter">$paramName</code></span>): <span class="type"><a href="extensionname.classpage.html" class="type Extension\Namespace\Existing_Class">\Extension\Namespace\Existing_Class</a></span></div>

</div>

</div>
4 changes: 4 additions & 0 deletions tests/package/php/constant_links_001.phpt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,10 @@ Content:
<p class="para">
<strong><code><a href="extensionname2.constantspage2.html#vendor-namespace.constants.definitely-exists2">Vendor\Namespace::DEFINITELY_EXISTS2</a></code></strong>
</p>
<strong><code><a href="extensionname.constantspage.html#constant.extension-namespace-definitely-exists">\Extension\Namespace\DEFINITELY_EXISTS</a></code></strong>
<p class="para">
<strong><code><a href="extensionname2.constantspage2.html#vendor-namespace.constants.definitely-exists2">\Vendor\Namespace::DEFINITELY_EXISTS2</a></code></strong>
</p>
</div>

<div class="section">
Expand Down
32 changes: 32 additions & 0 deletions tests/package/php/data/class_and_method_link_rendering_001.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
<?xml version="1.0" encoding="utf-8"?>
<chapter xml:id="class_and_method_link_rendering" xmlns="http://docbook.org/ns/docbook">

<section>
<para>1. Class linking</para>
<classname>Extension\Namespace\Existing_Class</classname>
<classname>\Extension\Namespace\Existing_Class</classname>
</section>

<section>
<para>2. Method/Function linking</para>
<methodname>Extension\Namespace\Classname::existingMethodName</methodname>
<methodname>\Extension\Namespace\Classname::existingMethodName</methodname>
</section>

<section>
<para>3. Class linking (non-FQN) in method/function parameter and return type</para>
<methodsynopsis>
<type>Extension\Namespace\Existing_Class</type><methodname>method_name</methodname>
<methodparam><type>Extension\Namespace\Existing_Class</type><parameter>paramName</parameter></methodparam>
</methodsynopsis>
</section>

<section>
<para>4. Class linking (FQN) in method/function parameter and return type</para>
<methodsynopsis>
<type>\Extension\Namespace\Existing_Class</type><methodname>method_name</methodname>
<methodparam><type>\Extension\Namespace\Existing_Class</type><parameter>paramName</parameter></methodparam>
</methodsynopsis>
</section>

</chapter>
4 changes: 4 additions & 0 deletions tests/package/php/data/constant_links.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@
<para>
<constant>Vendor\Namespace::DEFINITELY_EXISTS2</constant>
</para>
<constant>\Extension\Namespace\DEFINITELY_EXISTS</constant>
<para>
<constant>\Vendor\Namespace::DEFINITELY_EXISTS2</constant>
</para>
</section>

<section>
Expand Down
10 changes: 10 additions & 0 deletions tests/package/php/data/property_linking.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,5 +30,15 @@
<property>Extension\Class::$__leadingAndTrailingUndescores2__</property>
</para>
</section>

<section>
<para>4. Properties (FQN)</para>
<para>
<property>\Vendor\Namespace::$definitely_exists</property>
</para>
<para>
<property>\Vendor\Namespace::$definitelyExists2</property>
</para>
</section>

</chapter>
10 changes: 10 additions & 0 deletions tests/package/php/property_linking.phpt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,5 +83,15 @@ Content:
<span class="property"><a href="extensionname2.page2.html#extension-class.props.leadingandtrailingundescores2">Extension\Class::$__leadingAndTrailingUndescores2__</a></span>
</p>
</div>

<div class="section">
<p class="para">%d. Properties (FQN)</p>
<p class="para">
<span class="property"><a href="extensionname.page.html#vendor-namespace.props.definitely-exists">\Vendor\Namespace::$definitely_exists</a></span>
</p>
<p class="para">
<span class="property"><a href="extensionname.page.html#vendor-namespace.props.definitelyexists2">\Vendor\Namespace::$definitelyExists2</a></span>
</p>
</div>

</div>
Loading