Skip to content

Commit 18f6ef6

Browse files
kristoff-itkristoff-it
committed
autodoc: improve linking of decl references
there are still some bugs to solve when a decl is re-exported but straight-forward cases are handled correctly
1 parent 87b2234 commit 18f6ef6

File tree

1 file changed

+78
-91
lines changed

1 file changed

+78
-91
lines changed

‎lib/docs/main.js‎

Lines changed: 78 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -93,8 +93,7 @@ var zigAnalysis;
9393
// empty array means refers to the package itself
9494
declNames: [],
9595
// these will be all types, except the last one may be a type or a decl
96-
declObjs: [],
97-
96+
declObjs: [],
9897
// (a, b, c, d) comptime call; result is the value the docs refer to
9998
callName: null,
10099
};
@@ -451,6 +450,8 @@ var zigAnalysis;
451450
curNav.declObjs.push(currentType);
452451
}
453452

453+
454+
454455
window.x = currentType;
455456

456457
renderNav();
@@ -819,6 +820,27 @@ var zigAnalysis;
819820
return navLink(curNav.pkgNames, curNav.declNames.concat([childName]));
820821
}
821822

823+
function findDeclNavLink(declName) {
824+
if (curNav.declObjs.length == 0) return null;
825+
const curFile = getAstNode(curNav.declObjs[curNav.declObjs.length-1].src).file;
826+
827+
for (let i = curNav.declObjs.length -1; i >= 0; i--) {
828+
const curDecl = curNav.declObjs[i];
829+
const curDeclName = curNav.declNames[i-1];
830+
if (curDeclName == declName) {
831+
const declPath = curNav.declNames.slice(0,i);
832+
return navLink(curNav.pkgNames, declPath);
833+
}
834+
835+
if (findSubDecl(curDecl, declName) != null) {
836+
const declPath = curNav.declNames.slice(0,i).concat([declName]);
837+
return navLink(curNav.pkgNames, declPath);
838+
}
839+
}
840+
841+
//throw("could not resolve links for '" + declName + "'");
842+
}
843+
822844
//
823845
// function navLinkCall(callObj) {
824846
// let declNamesCopy = curNav.declNames.concat([]);
@@ -879,7 +901,7 @@ var zigAnalysis;
879901
return "false";
880902
}
881903
case "&": {
882-
return "&" + exprName(zigAnalysis.exprs[expr["&"]]);
904+
return "&" + exprName(zigAnalysis.exprs[expr["&"]], opts);
883905
}
884906
case "compileError": {
885907
let compileError = expr.compileError;
@@ -896,26 +918,26 @@ var zigAnalysis;
896918
let payloadHtml = "";
897919
const lhsExpr = zigAnalysis.exprs[expr.slice.lhs];
898920
const startExpr = zigAnalysis.exprs[expr.slice.start];
899-
let decl = exprName(lhsExpr);
900-
let start = exprName(startExpr);
921+
let decl = exprName(lhsExpr, opts);
922+
let start = exprName(startExpr, opts);
901923
let end = "";
902924
let sentinel = "";
903925
if (expr.slice["end"]) {
904926
const endExpr = zigAnalysis.exprs[expr.slice.end];
905-
let end_ = exprName(endExpr);
927+
let end_ = exprName(endExpr, opts);
906928
end += end_;
907929
}
908930
if (expr.slice["sentinel"]) {
909931
const sentinelExpr = zigAnalysis.exprs[expr.slice.sentinel];
910-
let sentinel_ = exprName(sentinelExpr);
932+
let sentinel_ = exprName(sentinelExpr, opts);
911933
sentinel += " :" + sentinel_;
912934
}
913935
payloadHtml += decl + "[" + start + ".." + end + sentinel + "]";
914936
return payloadHtml;
915937
}
916938
case "sliceIndex": {
917939
const sliceIndex = zigAnalysis.exprs[expr.sliceIndex];
918-
return exprName(sliceIndex, opts);
940+
return exprName(sliceIndex, opts, opts);
919941
}
920942
case "cmpxchg": {
921943
const typeIndex = zigAnalysis.exprs[expr.cmpxchg.type];
@@ -1019,19 +1041,6 @@ var zigAnalysis;
10191041
const switchIndex = zigAnalysis.exprs[expr.switchIndex];
10201042
return exprName(switchIndex, opts);
10211043
}
1022-
case "refPath": {
1023-
let name = exprName(expr.refPath[0]);
1024-
for (let i = 1; i < expr.refPath.length; i++) {
1025-
let component = undefined;
1026-
if ("string" in expr.refPath[i]) {
1027-
component = expr.refPath[i].string;
1028-
} else {
1029-
component = exprName(expr.refPath[i]);
1030-
}
1031-
name += "." + component;
1032-
}
1033-
return name;
1034-
}
10351044
case "fieldRef": {
10361045
const enumObj = exprName({ type: expr.fieldRef.type }, opts);
10371046
const field =
@@ -1581,10 +1590,46 @@ var zigAnalysis;
15811590
return exprName(exprArg, opts);
15821591
}
15831592
case "declRef": {
1584-
return getDecl(expr.declRef).name;
1593+
const name = getDecl(expr.declRef).name;
1594+
1595+
if (opts.wantHtml) {
1596+
let payloadHtml = "";
1597+
if (opts.wantLink) {
1598+
payloadHtml += '<a href="'+ findDeclNavLink(name) +'">';
1599+
}
1600+
payloadHtml +=
1601+
'<span class="tok-kw" style="color:lightblue;">' +
1602+
name +
1603+
"</span>";
1604+
if (opts.wantLink) payloadHtml += "</a>";
1605+
return payloadHtml;
1606+
} else {
1607+
return name;
1608+
}
15851609
}
15861610
case "refPath": {
1587-
return expr.refPath.map((x) => exprName(x, opts)).join(".");
1611+
let firstComponent = expr.refPath[0];
1612+
let name = exprName(firstComponent, opts);
1613+
let url = undefined;
1614+
if (opts.wantLink && "declRef" in firstComponent) {
1615+
url = findDeclNavLink(getDecl(firstComponent.declRef).name);
1616+
}
1617+
for (let i = 1; i < expr.refPath.length; i++) {
1618+
let component = undefined;
1619+
if ("string" in expr.refPath[i]) {
1620+
component = expr.refPath[i].string;
1621+
} else {
1622+
component = exprName(expr.refPath[i], {...opts, wantLink: false});
1623+
if (opts.wantLink && "declRef" in expr.refPath[i]) {
1624+
url += "." + getDecl(expr.refPath[i].declRef).name;
1625+
component = '<a href="'+ url +'">' +
1626+
component +
1627+
"</a>";
1628+
}
1629+
}
1630+
name += "." + component;
1631+
}
1632+
return name;
15881633
}
15891634
case "int": {
15901635
return "" + expr.int;
@@ -1929,78 +1974,20 @@ var zigAnalysis;
19291974
if (isVarArgs && i === fnObj.params.length - 1) {
19301975
payloadHtml += "...";
19311976
} else if ("alignOf" in value) {
1932-
if (opts.wantHtml) {
1933-
payloadHtml += '<a href="">';
1934-
payloadHtml +=
1935-
'<span class="tok-kw" style="color:lightblue;">' +
1936-
exprName(value, opts) +
1937-
"</span>";
1938-
payloadHtml += "</a>";
1939-
} else {
1940-
payloadHtml += exprName(value, opts);
1941-
}
1977+
payloadHtml += exprName(value, opts);
19421978
} else if ("typeOf" in value) {
1943-
if (opts.wantHtml) {
1944-
payloadHtml += '<a href="">';
1945-
payloadHtml +=
1946-
'<span class="tok-kw" style="color:lightblue;">' +
1947-
exprName(value, opts) +
1948-
"</span>";
1949-
payloadHtml += "</a>";
1950-
} else {
1951-
payloadHtml += exprName(value, opts);
1952-
}
1979+
payloadHtml += exprName(value, opts);
19531980
} else if ("typeOf_peer" in value) {
1954-
if (opts.wantHtml) {
1955-
payloadHtml += '<a href="">';
1956-
payloadHtml +=
1957-
'<span class="tok-kw" style="color:lightblue;">' +
1958-
exprName(value, opts) +
1959-
"</span>";
1960-
payloadHtml += "</a>";
1961-
} else {
19621981
payloadHtml += exprName(value, opts);
1963-
}
19641982
} else if ("declRef" in value) {
1965-
if (opts.wantHtml) {
1966-
payloadHtml += '<a href="">';
1967-
payloadHtml +=
1968-
'<span class="tok-kw" style="color:lightblue;">' +
1969-
exprName(value, opts) +
1970-
"</span>";
1971-
payloadHtml += "</a>";
1972-
} else {
19731983
payloadHtml += exprName(value, opts);
1974-
}
19751984
} else if ("call" in value) {
1976-
if (opts.wantHtml) {
1977-
payloadHtml += '<a href="">';
1978-
payloadHtml +=
1979-
'<span class="tok-kw" style="color:lightblue;">' +
1980-
exprName(value, opts) +
1981-
"</span>";
1982-
payloadHtml += "</a>";
1983-
} else {
19841985
payloadHtml += exprName(value, opts);
1985-
}
19861986
} else if ("refPath" in value) {
1987-
if (opts.wantHtml) {
1988-
payloadHtml += '<a href="">';
1989-
payloadHtml +=
1990-
'<span class="tok-kw" style="color:lightblue;">' +
1991-
exprName(value, opts) +
1992-
"</span>";
1993-
payloadHtml += "</a>";
1994-
} else {
19951987
payloadHtml += exprName(value, opts);
1996-
}
19971988
} else if ("type" in value) {
1998-
let name = exprName(value, {
1999-
...opts,
2000-
wantHtml: false,
2001-
wantLink: false,
2002-
});
2003-
payloadHtml += '<span class="tok-kw">' + name + "</span>";
1989+
payloadHtml += exprName(value, opts);
1990+
//payloadHtml += '<span class="tok-kw">' + name + "</span>";
20041991
} else if ("binOpIndex" in value) {
20051992
payloadHtml += exprName(value, opts);
20061993
} else if ("comptimeExpr" in value) {
@@ -2405,11 +2392,10 @@ var zigAnalysis;
24052392
}
24062393

24072394
if (typesList.length !== 0) {
2408-
window.x = typesList;
24092395
resizeDomList(
24102396
domListTypes,
24112397
typesList.length,
2412-
'<li><a href="#"></a></li>'
2398+
'<li><a href=""></a></li>'
24132399
);
24142400
for (let i = 0; i < typesList.length; i += 1) {
24152401
let liDom = domListTypes.children[i];
@@ -2511,8 +2497,7 @@ var zigAnalysis;
25112497
} else {
25122498
let fieldTypeExpr = container.fields[i];
25132499
html += ": ";
2514-
let name = exprName(fieldTypeExpr, false, false);
2515-
html += '<span class="tok-kw">' + name + "</span>";
2500+
html += exprName(fieldTypeExpr, {wantHtml:true, wantLink:true});
25162501
let tsn = typeShorthandName(fieldTypeExpr);
25172502
if (tsn) {
25182503
html += "<span> (" + tsn + ")</span>";
@@ -2746,13 +2731,15 @@ var zigAnalysis;
27462731
}
27472732
}
27482733

2749-
function findSubDecl(parentType, childName) {
2734+
function findSubDecl(parentTypeOrDecl, childName) {
2735+
let parentType = parentTypeOrDecl;
27502736
{
2751-
// Generic functions
2737+
// Generic functions / resorlving decls
27522738
if ("value" in parentType) {
27532739
const rv = resolveValue(parentType.value);
27542740
if ("type" in rv.expr) {
27552741
const t = getType(rv.expr.type);
2742+
parentType = t;
27562743
if (t.kind == typeKinds.Fn && t.generic_ret != null) {
27572744
let resolvedGenericRet = resolveValue({ expr: t.generic_ret });
27582745

0 commit comments

Comments
 (0)