authorgravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2022-02-22 20:18:45+01:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2022-07-19 19:10:11-07:00
log253e7e112e06d899e7b51194a637f4fddc6c1d65
treed4934c712bcc04579758fc8f89ee12ec4ff0b22d
parentfbf0d0bee9c37c24b0b54962eaf05a535e814bc9

autodoc: add frontend support for optionals & generic cleanup


1 files changed, 137 insertions(+), 117 deletions(-)

lib/docs/main.js+137-117
...@@ -149,8 +149,9 @@...@@ -149,8 +149,9 @@
149 while(i < 1000) {149 while(i < 1000) {
150 i += 1;150 i += 1;
151151
152 if ("declRef" in value) {152 if ("declPath" in value) {
153 value = zigAnalysis.decls[value.declRef].value;153 console.assert(value.declPath.length == 1); // only support declRefs for now
154 value = zigAnalysis.decls[value.declPath[0]].value;
154 continue;155 continue;
155 }156 }
156157
...@@ -169,8 +170,9 @@...@@ -169,8 +170,9 @@
169 return typeTypeId;170 return typeTypeId;
170 }171 }
171172
172 if ("declRef" in decl.value) {173 if ("declPath" in decl.value) {
173 decl = zigAnalysis.decls[decl.value.declRef];174 console.assert(decl.value.declPath.length == 1); // only support declRefs for now
175 decl = zigAnalysis.decls[decl.value.declPath[0]];
174 continue;176 continue;
175 }177 }
176178
...@@ -193,6 +195,7 @@...@@ -193,6 +195,7 @@
193195
194 console.log("TODO: handle in `typeOfDecl` more cases: ", decl);196 console.log("TODO: handle in `typeOfDecl` more cases: ", decl);
195 console.assert(false);197 console.assert(false);
198 throw {};
196 }199 }
197 console.assert(false);200 console.assert(false);
198 }201 }
...@@ -637,6 +640,25 @@...@@ -637,6 +640,25 @@
637 }640 }
638641
639 function typeIndexName(typeIndex, wantHtml, wantLink, fnDecl, linkFnNameDecl) {642 function typeIndexName(typeIndex, wantHtml, wantLink, fnDecl, linkFnNameDecl) {
643 return typeValueName({ type: typeIndex }, wantHtml, wantLink, fnDecl, linkFnNameDecl);
644 }
645
646 function typeValueName(typeValue, wantHtml, wantLink, fnDecl, linkFnNameDecl) {
647 if ("declPath" in typeValue) {
648 console.assert(typeValue.declPath.length == 1);
649 var declIndex = typeValue.declPath[0];
650 var name = zigAnalysis.decls[declIndex].name;
651 var declPath = getCanonDeclPath(declIndex);
652 if (wantLink) {
653 var nl = navLink(declPath.pkgNames, declPath.declNames);
654 return '<a href="' + nl + '">' + name + '</a>';
655 } else {
656 return name;
657 }
658 }
659
660 console.assert("type" in typeValue)
661 var typeIndex = typeValue.type;
640 var typeObj = zigAnalysis.types[typeIndex];662 var typeObj = zigAnalysis.types[typeIndex];
641 var declNameOk = declCanRepresentTypeKind(typeObj.kind);663 var declNameOk = declCanRepresentTypeKind(typeObj.kind);
642 if (wantLink) {664 if (wantLink) {
...@@ -714,10 +736,11 @@...@@ -714,10 +736,11 @@
714 name += typeObj.len;736 name += typeObj.len;
715 }737 }
716 name += "]";738 name += "]";
717 name += typeIndexName(typeObj.elem, wantHtml, wantSubLink, null);739 name += typeValueName(typeObj.elem, wantHtml, wantSubLink, null);
718 return name;740 return name;
719 case typeKinds.Optional:741 case typeKinds.Optional:
720 return "?" + typeIndexName(typeObj.child, wantHtml, wantSubLink, fnDecl, linkFnNameDecl);742
743 return "?" + typeValueName(typeObj.child, wantHtml, wantSubLink, fnDecl, linkFnNameDecl);
721 case typeKinds.Pointer:744 case typeKinds.Pointer:
722 var name = "";745 var name = "";
723 switch (typeObj.len) {746 switch (typeObj.len) {
...@@ -776,7 +799,7 @@...@@ -776,7 +799,7 @@
776 }799 }
777 name += ") ";800 name += ") ";
778 }801 }
779 name += typeIndexName(typeObj.elem, wantHtml, wantSubLink, null);802 name += typeValueName(typeObj.elem, wantHtml, wantSubLink, null);
780 return name;803 return name;
781 case typeKinds.Float:804 case typeKinds.Float:
782 if (wantHtml) {805 if (wantHtml) {
...@@ -949,13 +972,9 @@...@@ -949,13 +972,9 @@
949 }972 }
950 }973 }
951974
952 var retValue = resolveValue(typeObj.ret);975 payloadHtml += ') ';
953 console.assert("type" in retValue);976 if (typeObj.ret != null) {
954 var retTypeIndex = retValue.type;977 payloadHtml += typeValueName(typeObj.ret, wantHtml, wantSubLink, fnDecl);
955
956 payloadHtml += ') ';
957 if (retTypeIndex != null) {
958 payloadHtml += typeIndexName(retTypeIndex, wantHtml, wantSubLink, fnDecl);
959 } else if (wantHtml) {978 } else if (wantHtml) {
960 payloadHtml += '<span class="tok-kw">anytype</span>';979 payloadHtml += '<span class="tok-kw">anytype</span>';
961 } else {980 } else {
...@@ -1188,10 +1207,10 @@...@@ -1188,10 +1207,10 @@
1188 var kind = value.kind;1207 var kind = value.kind;
1189 if (kind === typeKinds.Fn) {1208 if (kind === typeKinds.Fn) {
1190 //if (allCompTimeFnCallsHaveTypeResult(decl.type, declTypeId)) {1209 //if (allCompTimeFnCallsHaveTypeResult(decl.type, declTypeId)) {
1191 // typesList.push(decl);1210 // typesList.push(decl);
1192 //} else {1211 //} else {
1193 fnsList.push(decl);1212 fnsList.push(decl);
1194 // }1213 // }
11951214
1196 } else if (typeIsErrSet(declValue.type)) {1215 } else if (typeIsErrSet(declValue.type)) {
1197 errSetsList.push(decl);1216 errSetsList.push(decl);
...@@ -1295,8 +1314,9 @@...@@ -1295,8 +1314,9 @@
1295 if (typeof(field) === 'object') {1314 if (typeof(field) === 'object') {
1296 if (field.failure === true) {1315 if (field.failure === true) {
1297 html += '<span class="tok-kw" style="color:red;">#FAILURE#</span>';1316 html += '<span class="tok-kw" style="color:red;">#FAILURE#</span>';
1298 } else if ("declRef" in field) {1317 } else if ("declPath" in field) {
1299 var decl = zigAnalysis.decls[field.declRef];1318 console.assert(field.declPath.lenght == 1);
1319 var decl = zigAnalysis.decls[field.declPath[0]];
1300 var val = resolveValue(decl.value);1320 var val = resolveValue(decl.value);
1301 console.assert("type" in val);1321 console.assert("type" in val);
1302 var valType = zigAnalysis.types[val.type];1322 var valType = zigAnalysis.types[val.type];
...@@ -2002,117 +2022,117 @@...@@ -2002,117 +2022,117 @@
2002 }2022 }
2003 }2023 }
20042024
2005 function showHelpModal() {2025function showHelpModal() {
2006 domHelpModal.classList.remove("hidden");2026 domHelpModal.classList.remove("hidden");
2007 domHelpModal.style.left = (window.innerWidth / 2 - domHelpModal.clientWidth / 2) + "px";2027 domHelpModal.style.left = (window.innerWidth / 2 - domHelpModal.clientWidth / 2) + "px";
2008 domHelpModal.style.top = (window.innerHeight / 2 - domHelpModal.clientHeight / 2) + "px";2028 domHelpModal.style.top = (window.innerHeight / 2 - domHelpModal.clientHeight / 2) + "px";
2009 domHelpModal.focus();2029 domHelpModal.focus();
2010 }2030}
2011
2012 function clearAsyncSearch() {
2013 if (searchTimer != null) {
2014 clearTimeout(searchTimer);
2015 searchTimer = null;
2016 }
2017 }
20182031
2019 function startAsyncSearch() {2032function clearAsyncSearch() {
2020 clearAsyncSearch();2033 if (searchTimer != null) {
2021 searchTimer = setTimeout(startSearch, 100);2034 clearTimeout(searchTimer);
2035 searchTimer = null;
2022 }2036 }
2023 function startSearch() {2037}
2024 clearAsyncSearch();
2025 var oldHash = location.hash;
2026 var parts = oldHash.split("?");
2027 var newPart2 = (domSearch.value === "") ? "" : ("?" + domSearch.value);
2028 location.hash = (parts.length === 1) ? (oldHash + newPart2) : (parts[0] + newPart2);
2029 }
2030 function getSearchTerms() {
2031 var list = curNavSearch.trim().split(/[ \r\n\t]+/);
2032 list.sort();
2033 return list;
2034 }
2035 function renderSearch() {
2036 var matchedItems = [];
2037 var ignoreCase = (curNavSearch.toLowerCase() === curNavSearch);
2038 var terms = getSearchTerms();
2039
2040 decl_loop: for (var declIndex = 0; declIndex < zigAnalysis.decls.length; declIndex += 1) {
2041 var canonPath = getCanonDeclPath(declIndex);
2042 if (canonPath == null) continue;
20432038
2044 var decl = zigAnalysis.decls[declIndex];2039function startAsyncSearch() {
2045 var lastPkgName = canonPath.pkgNames[canonPath.pkgNames.length - 1];2040 clearAsyncSearch();
2046 var fullPathSearchText = lastPkgName + "." + canonPath.declNames.join('.');2041 searchTimer = setTimeout(startSearch, 100);
2047 var astNode = zigAnalysis.astNodes[decl.src];2042}
2048 var fileAndDocs = zigAnalysis.files[astNode.file];2043function startSearch() {
2049 if (astNode.docs != null) {2044 clearAsyncSearch();
2050 fileAndDocs += "\n" + astNode.docs;2045 var oldHash = location.hash;
2046 var parts = oldHash.split("?");
2047 var newPart2 = (domSearch.value === "") ? "" : ("?" + domSearch.value);
2048 location.hash = (parts.length === 1) ? (oldHash + newPart2) : (parts[0] + newPart2);
2049}
2050function getSearchTerms() {
2051 var list = curNavSearch.trim().split(/[ \r\n\t]+/);
2052 list.sort();
2053 return list;
2054}
2055function renderSearch() {
2056 var matchedItems = [];
2057 var ignoreCase = (curNavSearch.toLowerCase() === curNavSearch);
2058 var terms = getSearchTerms();
2059
2060 decl_loop: for (var declIndex = 0; declIndex < zigAnalysis.decls.length; declIndex += 1) {
2061 var canonPath = getCanonDeclPath(declIndex);
2062 if (canonPath == null) continue;
2063
2064 var decl = zigAnalysis.decls[declIndex];
2065 var lastPkgName = canonPath.pkgNames[canonPath.pkgNames.length - 1];
2066 var fullPathSearchText = lastPkgName + "." + canonPath.declNames.join('.');
2067 var astNode = zigAnalysis.astNodes[decl.src];
2068 var fileAndDocs = zigAnalysis.files[astNode.file];
2069 if (astNode.docs != null) {
2070 fileAndDocs += "\n" + astNode.docs;
2071 }
2072 var fullPathSearchTextLower = fullPathSearchText;
2073 if (ignoreCase) {
2074 fullPathSearchTextLower = fullPathSearchTextLower.toLowerCase();
2075 fileAndDocs = fileAndDocs.toLowerCase();
2076 }
2077
2078 var points = 0;
2079 for (var termIndex = 0; termIndex < terms.length; termIndex += 1) {
2080 var term = terms[termIndex];
2081
2082 // exact, case sensitive match of full decl path
2083 if (fullPathSearchText === term) {
2084 points += 4;
2085 continue;
2051 }2086 }
2052 var fullPathSearchTextLower = fullPathSearchText;2087 // exact, case sensitive match of just decl name
2053 if (ignoreCase) {2088 if (decl.name == term) {
2054 fullPathSearchTextLower = fullPathSearchTextLower.toLowerCase();2089 points += 3;
2055 fileAndDocs = fileAndDocs.toLowerCase();2090 continue;
2056 }2091 }
20572092 // substring, case insensitive match of full decl path
2058 var points = 0;2093 if (fullPathSearchTextLower.indexOf(term) >= 0) {
2059 for (var termIndex = 0; termIndex < terms.length; termIndex += 1) {2094 points += 2;
2060 var term = terms[termIndex];2095 continue;
20612096 }
2062 // exact, case sensitive match of full decl path2097 if (fileAndDocs.indexOf(term) >= 0) {
2063 if (fullPathSearchText === term) {2098 points += 1;
2064 points += 4;2099 continue;
2065 continue;
2066 }
2067 // exact, case sensitive match of just decl name
2068 if (decl.name == term) {
2069 points += 3;
2070 continue;
2071 }
2072 // substring, case insensitive match of full decl path
2073 if (fullPathSearchTextLower.indexOf(term) >= 0) {
2074 points += 2;
2075 continue;
2076 }
2077 if (fileAndDocs.indexOf(term) >= 0) {
2078 points += 1;
2079 continue;
2080 }
2081
2082 continue decl_loop;
2083 }2100 }
20842101
2085 matchedItems.push({2102 continue decl_loop;
2086 decl: decl,
2087 path: canonPath,
2088 points: points,
2089 });
2090 }2103 }
20912104
2092 if (matchedItems.length !== 0) {2105 matchedItems.push({
2093 resizeDomList(domListSearchResults, matchedItems.length, '<li><a href="#"></a></li>');2106 decl: decl,
2107 path: canonPath,
2108 points: points,
2109 });
2110 }
20942111
2095 matchedItems.sort(function(a, b) {2112 if (matchedItems.length !== 0) {
2096 var cmp = operatorCompare(b.points, a.points);2113 resizeDomList(domListSearchResults, matchedItems.length, '<li><a href="#"></a></li>');
2097 if (cmp != 0) return cmp;
2098 return operatorCompare(a.decl.name, b.decl.name);
2099 });
21002114
2101 for (var i = 0; i < matchedItems.length; i += 1) {2115 matchedItems.sort(function(a, b) {
2102 var liDom = domListSearchResults.children[i];2116 var cmp = operatorCompare(b.points, a.points);
2103 var aDom = liDom.children[0];2117 if (cmp != 0) return cmp;
2104 var match = matchedItems[i];2118 return operatorCompare(a.decl.name, b.decl.name);
2105 var lastPkgName = match.path.pkgNames[match.path.pkgNames.length - 1];2119 });
2106 aDom.textContent = lastPkgName + "." + match.path.declNames.join('.');
2107 aDom.setAttribute('href', navLink(match.path.pkgNames, match.path.declNames));
2108 }
2109 renderSearchCursor();
21102120
2111 domSectSearchResults.classList.remove("hidden");2121 for (var i = 0; i < matchedItems.length; i += 1) {
2112 } else {2122 var liDom = domListSearchResults.children[i];
2113 domSectSearchNoResults.classList.remove("hidden");2123 var aDom = liDom.children[0];
2124 var match = matchedItems[i];
2125 var lastPkgName = match.path.pkgNames[match.path.pkgNames.length - 1];
2126 aDom.textContent = lastPkgName + "." + match.path.declNames.join('.');
2127 aDom.setAttribute('href', navLink(match.path.pkgNames, match.path.declNames));
2114 }2128 }
2129 renderSearchCursor();
2130
2131 domSectSearchResults.classList.remove("hidden");
2132 } else {
2133 domSectSearchNoResults.classList.remove("hidden");
2115 }2134 }
2135}
21162136
2117function renderSearchCursor() {2137function renderSearchCursor() {
2118 for (var i = 0; i < domListSearchResults.children.length; i += 1) {2138 for (var i = 0; i < domListSearchResults.children.length; i += 1) {