[clang-tools-extra] [clang-doc]: Enable horizontal wrapping on longer function definitions (PR #181417)
Samrudh Nelli via cfe-commits
cfe-commits at lists.llvm.org
Mon Feb 16 08:36:06 PST 2026
https://github.com/SamrudhNelli updated https://github.com/llvm/llvm-project/pull/181417
>From 5137041232b96451cd140ff157c61498827ca0da Mon Sep 17 00:00:00 2001
From: Samrudh Nelli <samrudhnelli at gmail.com>
Date: Fri, 13 Feb 2026 22:38:54 +0530
Subject: [PATCH 1/3] fix: Enable horizontal wrapping on longer function
definitions
Could not figure out how to use the {{^End}} on the just
the inner scope as it would revert to the outer scope with {{End}} set
for the final function.
Hence, reverted to trailing commas for all parameters.
erbtehagf
jket
---
clang-tools-extra/clang-doc/JSONGenerator.cpp | 7 ++++--
.../clang-doc/assets/clang-doc-mustache.css | 22 +++++++++++++++++++
.../assets/function-template.mustache | 3 +--
3 files changed, 28 insertions(+), 4 deletions(-)
diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index 5051e7e6e690d..c3c14b9ee6f4e 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp
@@ -452,8 +452,7 @@ static void serializeArray(const Container &Records, Object &Obj,
json::Value ItemVal = Object();
auto &ItemObj = *ItemVal.getAsObject();
SerializeInfo(Records[Index], ItemObj);
- if (Index == Records.size() - 1)
- ItemObj["End"] = true;
+ ItemObj["End"] = (Index == Records.size() - 1);
RecordsArrayRef.push_back(ItemVal);
}
Obj[Key] = RecordsArray;
@@ -536,10 +535,14 @@ static void serializeInfo(const FunctionInfo &F, json::Object &Obj,
const std::optional<StringRef> RepositoryLine) {
serializeCommonAttributes(F, Obj, RepositoryURL, RepositoryLine);
Obj["IsStatic"] = F.IsStatic;
+ size_t ParamLen = F.Name.size() + 1;
auto ReturnTypeObj = Object();
serializeInfo(F.ReturnType, ReturnTypeObj);
Obj["ReturnType"] = std::move(ReturnTypeObj);
+ ParamLen += F.ReturnType.Type.Name.size();
+ ParamLen += 2;
+ Obj["ParamLength"] = ParamLen;
if (!F.Params.empty())
serializeArray(F.Params, Obj, "Params", SerializeInfoLambda);
diff --git a/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css b/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css
index 19fba2f9eae76..922166d8ee258 100644
--- a/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css
+++ b/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css
@@ -520,3 +520,25 @@ a, a:visited, a:hover, a:active {
overflow: hidden;
padding: 10px;
}
+
+
+.params-vertical {
+ display: flex;
+ flex-wrap: wrap;
+}
+
+
+.param {
+ display: block;
+ margin-right: 5px;
+ padding-left: 100px;
+}
+
+.format-text {
+ color: #800;
+}
+
+.format-title {
+ color: #800;
+ font-weight: bold;
+}
\ No newline at end of file
diff --git a/clang-tools-extra/clang-doc/assets/function-template.mustache b/clang-tools-extra/clang-doc/assets/function-template.mustache
index 510219a63d379..64845bc2d89e6 100644
--- a/clang-tools-extra/clang-doc/assets/function-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/function-template.mustache
@@ -10,8 +10,7 @@
<pre><code class="language-cpp code-clang-doc">template <{{#Parameters}}{{Param}}{{^End}}, {{/End}}{{/Parameters}}></code></pre>
{{/Template}}
{{! Function Prototype }}
- <pre><code class="language-cpp code-clang-doc">{{ReturnType.QualName}} {{Name}}{{#Template}}{{#Specialization}}<{{#Parameters}}{{Param}}{{^End}}, {{/End}}{{/Parameters}}>{{/Specialization}}{{/Template}} ({{#Params}}{{Type.QualName}} {{Name}}{{^End}}, {{/End}}{{/Params}})</code></pre>
- {{! Function Comments }}
+ <pre><code class="nohighlight code-clang-doc"><span class="format-text">{{ReturnType.QualName}}</span> <span class="format-title">{{Name}}</span> (<span class="params-vertical" style="padding-left: {{ParamLength}}ch;">{{#Params}}<span class="param"><span class="format-text">{{Type.QualName}}</span> {{Name}}{{^End}}, {{/End}}</span>{{/Params}}</span><span class="params-vertical" style="padding-left: {{ParamLength}}ch;">)</span></code></pre>
{{#Description}}
<div class="doc-card">
{{>Comments}}
>From c8194948bc7935aee91faabb651d2e91253aefa4 Mon Sep 17 00:00:00 2001
From: Samrudh Nelli <samrudhnelli at gmail.com>
Date: Mon, 16 Feb 2026 20:00:01 +0530
Subject: [PATCH 2/3] implement approach 2 that falls back to approach 3 for
long functions
---
clang-tools-extra/clang-doc/JSONGenerator.cpp | 24 +++++++++++++++++--
.../clang-doc/assets/clang-doc-mustache.css | 1 -
.../assets/function-template.mustache | 2 +-
3 files changed, 23 insertions(+), 4 deletions(-)
diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index c3c14b9ee6f4e..ea1d26bb3d592 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp
@@ -455,6 +455,24 @@ static void serializeArray(const Container &Records, Object &Obj,
ItemObj["End"] = (Index == Records.size() - 1);
RecordsArrayRef.push_back(ItemVal);
}
+ if (Key == "Params") {
+ size_t TotalLength = 0;
+ for (const auto &Val : RecordsArrayRef) {
+ if (const auto *ItemObj = Val.getAsObject()) {
+ if (const auto *Type = ItemObj->get("Type"))
+ if(const auto *TypeObj = Type->getAsObject())
+ if(auto Name = TypeObj->getString("QualName"))
+ TotalLength += Name->size();
+ if (auto Name = ItemObj->getString("Name"))
+ TotalLength += Name->size();
+ TotalLength += 2; // For ', '
+ }
+ }
+ size_t ParamLen;
+ if(auto Length = Obj.getInteger("ParamLength"))
+ ParamLen = *Length;
+ Obj["IsLong"] = (TotalLength + ParamLen > 80);
+ }
Obj[Key] = RecordsArray;
}
@@ -473,8 +491,7 @@ static void serializeInfo(const ArrayRef<TemplateParamInfo> &Params,
Object &ParamObj = *ParamObjVal.getAsObject();
ParamObj["Param"] = Params[Idx].Contents;
- if (Idx == Params.size() - 1)
- ParamObj["End"] = true;
+ ParamObj["End"] = (Idx == Params.size() - 1);
ParamsArrayRef.push_back(ParamObjVal);
}
Obj["Parameters"] = ParamsArray;
@@ -547,6 +564,9 @@ static void serializeInfo(const FunctionInfo &F, json::Object &Obj,
if (!F.Params.empty())
serializeArray(F.Params, Obj, "Params", SerializeInfoLambda);
+ if(ParamLen >= 40)
+ Obj["ParamLength"] = 35;
+
if (F.Template)
serializeInfo(F.Template.value(), Obj);
}
diff --git a/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css b/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css
index 922166d8ee258..82f4f318ad578 100644
--- a/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css
+++ b/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css
@@ -531,7 +531,6 @@ a, a:visited, a:hover, a:active {
.param {
display: block;
margin-right: 5px;
- padding-left: 100px;
}
.format-text {
diff --git a/clang-tools-extra/clang-doc/assets/function-template.mustache b/clang-tools-extra/clang-doc/assets/function-template.mustache
index 64845bc2d89e6..fe49bb5fa421f 100644
--- a/clang-tools-extra/clang-doc/assets/function-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/function-template.mustache
@@ -10,7 +10,7 @@
<pre><code class="language-cpp code-clang-doc">template <{{#Parameters}}{{Param}}{{^End}}, {{/End}}{{/Parameters}}></code></pre>
{{/Template}}
{{! Function Prototype }}
- <pre><code class="nohighlight code-clang-doc"><span class="format-text">{{ReturnType.QualName}}</span> <span class="format-title">{{Name}}</span> (<span class="params-vertical" style="padding-left: {{ParamLength}}ch;">{{#Params}}<span class="param"><span class="format-text">{{Type.QualName}}</span> {{Name}}{{^End}}, {{/End}}</span>{{/Params}}</span><span class="params-vertical" style="padding-left: {{ParamLength}}ch;">)</span></code></pre>
+ <pre><code class="nohighlight code-clang-doc"><span class="format-text">{{ReturnType.QualName}}</span> <span class="format-title">{{Name}}</span> ({{#IsLong}}<span class="params-vertical" style="padding-left: {{ParamLength}}ch;">{{#Params}}<span class="param"><span class="format-text">{{Type.QualName}}</span> {{Name}}{{^End}}, {{/End}}</span>{{/Params}}</span><span class="param" style="padding-left: calc({{ParamLength}}ch - 1ch);">)</span>{{/IsLong}}{{^IsLong}}{{#Params}}{{Type.QualName}} {{Name}}{{^End}}, {{/End}}{{/Params}}){{/IsLong}}</code></pre>
{{#Description}}
<div class="doc-card">
{{>Comments}}
>From 651b7f9a0f5446915dacf3d721b1a99cdeee2250 Mon Sep 17 00:00:00 2001
From: Samrudh Nelli <samrudhnelli at gmail.com>
Date: Mon, 16 Feb 2026 22:04:25 +0530
Subject: [PATCH 3/3] use JS to check for long functions instead of hardcoding
the char limit
---
clang-tools-extra/clang-doc/JSONGenerator.cpp | 23 ++-----------
.../clang-doc/assets/clang-doc-mustache.css | 2 --
.../assets/function-template.mustache | 2 +-
.../clang-doc/assets/mustache-index.js | 32 +++++++++++++++++++
4 files changed, 35 insertions(+), 24 deletions(-)
diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index ea1d26bb3d592..de7405662479b 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp
@@ -455,24 +455,6 @@ static void serializeArray(const Container &Records, Object &Obj,
ItemObj["End"] = (Index == Records.size() - 1);
RecordsArrayRef.push_back(ItemVal);
}
- if (Key == "Params") {
- size_t TotalLength = 0;
- for (const auto &Val : RecordsArrayRef) {
- if (const auto *ItemObj = Val.getAsObject()) {
- if (const auto *Type = ItemObj->get("Type"))
- if(const auto *TypeObj = Type->getAsObject())
- if(auto Name = TypeObj->getString("QualName"))
- TotalLength += Name->size();
- if (auto Name = ItemObj->getString("Name"))
- TotalLength += Name->size();
- TotalLength += 2; // For ', '
- }
- }
- size_t ParamLen;
- if(auto Length = Obj.getInteger("ParamLength"))
- ParamLen = *Length;
- Obj["IsLong"] = (TotalLength + ParamLen > 80);
- }
Obj[Key] = RecordsArray;
}
@@ -560,13 +542,12 @@ static void serializeInfo(const FunctionInfo &F, json::Object &Obj,
ParamLen += F.ReturnType.Type.Name.size();
ParamLen += 2;
Obj["ParamLength"] = ParamLen;
+ if(ParamLen >= 40)
+ Obj["ParamLength"] = 35;
if (!F.Params.empty())
serializeArray(F.Params, Obj, "Params", SerializeInfoLambda);
- if(ParamLen >= 40)
- Obj["ParamLength"] = 35;
-
if (F.Template)
serializeInfo(F.Template.value(), Obj);
}
diff --git a/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css b/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css
index 82f4f318ad578..605d48c3b07cc 100644
--- a/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css
+++ b/clang-tools-extra/clang-doc/assets/clang-doc-mustache.css
@@ -521,13 +521,11 @@ a, a:visited, a:hover, a:active {
padding: 10px;
}
-
.params-vertical {
display: flex;
flex-wrap: wrap;
}
-
.param {
display: block;
margin-right: 5px;
diff --git a/clang-tools-extra/clang-doc/assets/function-template.mustache b/clang-tools-extra/clang-doc/assets/function-template.mustache
index fe49bb5fa421f..956a7c0ce6a94 100644
--- a/clang-tools-extra/clang-doc/assets/function-template.mustache
+++ b/clang-tools-extra/clang-doc/assets/function-template.mustache
@@ -10,7 +10,7 @@
<pre><code class="language-cpp code-clang-doc">template <{{#Parameters}}{{Param}}{{^End}}, {{/End}}{{/Parameters}}></code></pre>
{{/Template}}
{{! Function Prototype }}
- <pre><code class="nohighlight code-clang-doc"><span class="format-text">{{ReturnType.QualName}}</span> <span class="format-title">{{Name}}</span> ({{#IsLong}}<span class="params-vertical" style="padding-left: {{ParamLength}}ch;">{{#Params}}<span class="param"><span class="format-text">{{Type.QualName}}</span> {{Name}}{{^End}}, {{/End}}</span>{{/Params}}</span><span class="param" style="padding-left: calc({{ParamLength}}ch - 1ch);">)</span>{{/IsLong}}{{^IsLong}}{{#Params}}{{Type.QualName}} {{Name}}{{^End}}, {{/End}}{{/Params}}){{/IsLong}}</code></pre>
+ <pre><code class="nohighlight code-clang-doc"><span class="format-text">{{ReturnType.QualName}}</span> <span class="format-title">{{Name}}</span> (<span class="params-vertical" style="padding-left: {{ParamLength}}ch;">{{#Params}}<span class="param"><span class="format-text">{{Type.QualName}}</span> {{Name}}{{^End}}, {{/End}}</span>{{/Params}}</span><span class="param" style="padding-left: calc({{ParamLength}}ch - 1ch);">)</span></code></pre>
{{#Description}}
<div class="doc-card">
{{>Comments}}
diff --git a/clang-tools-extra/clang-doc/assets/mustache-index.js b/clang-tools-extra/clang-doc/assets/mustache-index.js
index 0f05eb71f0bee..b26fd6e60543f 100644
--- a/clang-tools-extra/clang-doc/assets/mustache-index.js
+++ b/clang-tools-extra/clang-doc/assets/mustache-index.js
@@ -21,6 +21,38 @@ document.addEventListener("DOMContentLoaded", function() {
el.classList.remove("hljs");
});
+ function getCharSize() {
+ const testChar = document.createElement('span');
+ testChar.className = "code-clang-doc"
+ testChar.style.visibility = 'hidden';
+ testChar.innerText = 'a';
+ document.body.appendChild(testChar);
+ const charWidth = testChar.getBoundingClientRect().width;
+ document.body.removeChild(testChar);
+ return charWidth;
+ }
+
+ function revertToSingleLine(func) {
+ const paramsContainer = func.querySelectorAll('.params-vertical')
+ const params = func.querySelectorAll('.param')
+ paramsContainer.forEach(params => {
+ params.style.display = "inline";
+ params.style.paddingLeft = "0px";
+ });
+ params.forEach(param => {
+ param.style.display = "inline";
+ param.style.paddingLeft = "0px";
+ });
+ }
+
+ const functions = document.querySelectorAll('.code-clang-doc');
+ const content = document.querySelector('.content')
+ const charSize = getCharSize();
+ functions.forEach(func => {
+ if(func.textContent.trim().length * charSize < content.clientWidth - 20)
+ revertToSingleLine(func)
+ });
+
document.querySelectorAll('.sidebar-item-container').forEach(item => {
item.addEventListener('click', function() {
const anchor = item.getElementsByTagName("a");
More information about the cfe-commits
mailing list