authorgravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2022-02-10 19:30:04+01:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2022-07-19 19:10:10-07:00
log564d6c4960018020913d3a2883cdd028f841af20
tree1e4465756c1942776a26ad502db92e00572163b5
parentb296f5ac023517a4cbf31abdab52cabcc2d3c1e7

autodocs: improve function rendering


1 files changed, 210 insertions(+), 165 deletions(-)

lib/docs/main.js+210-165
......@@ -118,6 +118,20 @@
118118 function declContainsType(x){
119119 console.assert("value" in x);
120120
121
122 }
123
124 function typeShorthandName(type) {
125 var name = type.name;
126 if (type.kind === typeKinds.Struct) {
127 name = "struct";
128 } else if (type.kind === typeKinds.Enum) {
129 name = "enum";
130 } else if (type.kind === typeKinds.Union) {
131 name= "union";
132 }
133
134 return name
121135 }
122136
123137 function typeKindIsContainer(typeKind) {
......@@ -169,7 +183,7 @@
169183 }
170184
171185 if ("struct" in decl.value) {
172 return resolveTypeRefToTypeId(decl.value.struct.typeRef);
186 return resolveTypeRefToTypeId(decl.value.struct.typeRef);
173187 }
174188
175189 console.log("TODO: handle in `resolveDeclValueTypeId` more cases: ", decl);
......@@ -251,7 +265,7 @@
251265
252266 var childDeclValue = resolveValue(childDecl.value);
253267 if ("type" in childDeclValue &&
254 zigAnalysis.types[childDeclValue.type].kind !== typeKinds.Fn){
268 zigAnalysis.types[childDeclValue.type].kind !== typeKinds.Fn){
255269 if (i + 1 === curNav.declNames.length) {
256270 curNav.declObjs.push(zigAnalysis.types[childDeclValue.type]);
257271 break;
......@@ -416,12 +430,29 @@
416430 }
417431 var divDom = domListParams.children[domIndex];
418432 domIndex += 1;
419 var value = resolveValue(typeObj.params[i]);
420 console.assert("type" in value);
421 var argTypeIndex = value.type;
433
434
435 var value = typeObj.params[i];
436 var valueType = resolveValue(value);
437 console.assert("type" in valueType);
438 var argTypeIndex = valueType.type;
422439 var html = '<pre>' + escapeHtml(fieldNode.name) + ": ";
423440 if (isVarArgs && i === typeObj.params.length - 1) {
424441 html += '...';
442 } else if ("declRef" in value) {
443 var decl = zigAnalysis.decls[value.declRef];
444 var val = resolveValue(decl.value);
445 var valType = zigAnalysis.types[argTypeIndex];
446
447 var valTypeName = typeShorthandName(valType);
448
449 html += '<a href="'+navLinkDecl(decl.name)+'">';
450 html += '<span class="tok-kw" style="color:lightblue;">' + decl.name + '</span>';
451 html += '</a>';
452 html += ' ('+ valTypeName +')';
453 } else if ("type" in value) {
454 var name = zigAnalysis.types[value.type].name;
455 html += '<span class="tok-kw">' + name + '</span>';
425456 } else if (argTypeIndex != null) {
426457 html += typeIndexName(argTypeIndex, true, true);
427458 } else {
......@@ -558,12 +589,12 @@
558589 var callName = declNamesCopy.pop();
559590
560591 callName += '(';
561 for (var arg_i = 0; arg_i < callObj.args.length; arg_i += 1) {
562 if (arg_i !== 0) callName += ',';
563 var argObj = callObj.args[arg_i];
564 callName += getValueText(argObj.type, argObj.value, false, false);
565 }
566 callName += ')';
592 for (var arg_i = 0; arg_i < callObj.args.length; arg_i += 1) {
593 if (arg_i !== 0) callName += ',';
594 var argObj = callObj.args[arg_i];
595 callName += getValueText(argObj.type, argObj.value, false, false);
596 }
597 callName += ')';
567598
568599 declNamesCopy.push(callName);
569600 return navLink(curNav.pkgNames, declNamesCopy);
......@@ -633,15 +664,15 @@
633664
634665 // TODO make these links work
635666 //var html = '<a href="' + navLinkCall(callObj) + '">' + escapeHtml(fnDecl.name) + '</a>(';
636 var html = escapeHtml(fnDecl.name) + '(';
637 for (var arg_i = 0; arg_i < callObj.args.length; arg_i += 1) {
638 if (arg_i !== 0) html += ', ';
639 var argObj = callObj.args[arg_i];
640 html += getValueText(argObj.type, argObj.value, true, true);
667 var html = escapeHtml(fnDecl.name) + '(';
668 for (var arg_i = 0; arg_i < callObj.args.length; arg_i += 1) {
669 if (arg_i !== 0) html += ', ';
670 var argObj = callObj.args[arg_i];
671 html += getValueText(argObj.type, argObj.value, true, true);
672 }
673 html += ')';
674 return html;
641675 }
642 html += ')';
643 return html;
644 }
645676
646677 function getValueText(typeIndex, value, wantHtml, wantLink) {
647678 var typeObj = zigAnalysis.types[typeIndex];
......@@ -677,7 +708,7 @@
677708 case typeKinds.Optional:
678709 return "?" + typeIndexName(typeObj.child, wantHtml, wantSubLink, fnDecl, linkFnNameDecl);
679710 case typeKinds.Pointer:
680 var name = "";
711 var name = "";
681712 switch (typeObj.len) {
682713 case pointerSizeEnum.One:
683714 default:
......@@ -832,72 +863,86 @@
832863 payloadHtml += 'fn'
833864 }
834865 payloadHtml += '(';
835 if (typeObj.params) {
836 var fields = null;
837 var isVarArgs = false;
838 var fnNode = zigAnalysis.astNodes[fnDecl.src];
839 fields = fnNode.fields;
840 isVarArgs = fnNode.varArgs;
841
842 for (var i = 0; i < typeObj.params.length; i += 1) {
843 if (i != 0) {
844 payloadHtml += ', ';
845 }
866 if (typeObj.params) {
867 var fields = null;
868 var isVarArgs = false;
869 var fnNode = zigAnalysis.astNodes[fnDecl.src];
870 fields = fnNode.fields;
871 isVarArgs = fnNode.varArgs;
872
873 for (var i = 0; i < typeObj.params.length; i += 1) {
874 if (i != 0) {
875 payloadHtml += ', ';
876 }
877 var value = typeObj.params[i];
878 var paramValue = resolveValue(value);
879 console.assert("type" in paramValue);
880 var argTypeIndex = paramValue.type;
846881
847 var paramValue = resolveValue(typeObj.params[i]);
848 console.assert("type" in paramValue);
849 var argTypeIndex = paramValue.type;
850882
851 if (fields != null) {
852 var paramNode = zigAnalysis.astNodes[fields[i]];
883 if (fields != null) {
884 var paramNode = zigAnalysis.astNodes[fields[i]];
853885
854 if (paramNode.varArgs) {
855 payloadHtml += '...';
856 continue;
857 }
886 if (paramNode.varArgs) {
887 payloadHtml += '...';
888 continue;
889 }
858890
859 if (paramNode.noalias) {
860 if (wantHtml) {
861 payloadHtml += '<span class="tok-kw">noalias</span> ';
862 } else {
863 payloadHtml += 'noalias ';
891 if (paramNode.noalias) {
892 if (wantHtml) {
893 payloadHtml += '<span class="tok-kw">noalias</span> ';
894 } else {
895 payloadHtml += 'noalias ';
896 }
864897 }
865 }
866898
867 if (paramNode.comptime) {
868 if (wantHtml) {
869 payloadHtml += '<span class="tok-kw">comptime</span> ';
870 } else {
871 payloadHtml += 'comptime ';
899 if (paramNode.comptime) {
900 if (wantHtml) {
901 payloadHtml += '<span class="tok-kw">comptime</span> ';
902 } else {
903 payloadHtml += 'comptime ';
904 }
872905 }
873 }
874906
875 var paramName = paramNode.name;
876 if (paramName != null) {
877 // skip if it matches the type name
878 if (argTypeIndex == null || !shouldSkipParamName(argTypeIndex, paramName)) {
879 payloadHtml += paramName + ': ';
907 var paramName = paramNode.name;
908 if (paramName != null) {
909 // skip if it matches the type name
910 if (argTypeIndex == null || !shouldSkipParamName(argTypeIndex, paramName)) {
911 payloadHtml += paramName + ': ';
912 }
880913 }
881914 }
882 }
883915
884 if (isVarArgs && i === typeObj.args.length - 1) {
885 payloadHtml += '...';
886 } else if (argTypeIndex != null) {
887 payloadHtml += typeIndexName(argTypeIndex, wantHtml, wantSubLink);
888 } else if (wantHtml) {
889 payloadHtml += '<span class="tok-kw">var</span>';
890 } else {
891 payloadHtml += 'var';
916 if (isVarArgs && i === typeObj.args.length - 1) {
917 payloadHtml += '...';
918 } else if ("declRef" in value) {
919 var decl = zigAnalysis.decls[value.declRef];
920 var val = resolveValue(decl.value);
921 var valType = zigAnalysis.types[argTypeIndex];
922
923 var valTypeName = typeShorthandName(valType);
924
925 payloadHtml += '<a href="'+navLinkDecl(decl.name)+'">';
926 payloadHtml += '<span class="tok-kw" style="color:lightblue;">' + decl.name + '</span>';
927 payloadHtml += '</a>';
928 } else if ("type" in value) {
929 var name = zigAnalysis.types[value.type].name;
930 payloadHtml += '<span class="tok-kw">' + name + '</span>';
931 } else if (argTypeIndex != null) {
932 payloadHtml += typeIndexName(argTypeIndex, wantHtml, wantSubLink);
933 } else if (wantHtml) {
934 payloadHtml += '<span class="tok-kw">var</span>';
935 } else {
936 payloadHtml += 'var';
937 }
892938 }
893939 }
894 }
895940
896 var retValue = resolveValue(typeObj.ret);
897 console.assert("type" in retValue);
898 var retTypeIndex = retValue.type;
941 var retValue = resolveValue(typeObj.ret);
942 console.assert("type" in retValue);
943 var retTypeIndex = retValue.type;
899944
900 payloadHtml += ') ';
945 payloadHtml += ') ';
901946 if (retTypeIndex != null) {
902947 payloadHtml += typeIndexName(retTypeIndex, wantHtml, wantSubLink, fnDecl);
903948 } else if (wantHtml) {
......@@ -1015,14 +1060,14 @@
10151060 var next = typeObj.pubDecls[declI];
10161061 if (prev === next) continue;
10171062 // TODO instead of showing "examples" as the public declarations,
1018 // do logic like this:
1063 // do logic like this:
10191064 //if (typeof(prev) !== 'object') {
1020 // var newDeclId = zigAnalysis.decls.length;
1021 // prev = clone(zigAnalysis.decls[prev]);
1022 // prev.id = newDeclId;
1023 // zigAnalysis.decls.push(prev);
1024 // containerObj.pubDecls[declI] = prev;
1025 //}
1065 // var newDeclId = zigAnalysis.decls.length;
1066 // prev = clone(zigAnalysis.decls[prev]);
1067 // prev.id = newDeclId;
1068 // zigAnalysis.decls.push(prev);
1069 // containerObj.pubDecls[declI] = prev;
1070 //}
10261071 //mergeDecls(prev, next, firstTypeObj, typeObj);
10271072 }
10281073 }
......@@ -1067,10 +1112,10 @@
10671112 switch(Object.keys(decl.value)[0]) {
10681113 case "int":
10691114 declValueText += decl.value.int.value;
1070 break;
1115 break;
10711116 case "float":
10721117 declValueText += decl.value.float.value;
1073 break;
1118 break;
10741119 default:
10751120 console.log("TODO: renderValue for ", Object.keys(decl.value)[0]);
10761121 declValueText += "#TODO#";
......@@ -1114,32 +1159,33 @@
11141159 var declLen = container.pubDecls ? container.pubDecls.length : 0;
11151160 for (var i = 0; i < declLen; i += 1) {
11161161 var decl = zigAnalysis.decls[container.pubDecls[i]];
1117 var declTypeId = resolveDeclValueTypeId(decl);
1162 var declValue = resolveValue(decl.value);
11181163
11191164 if (decl.kind === 'var') {
11201165 varsList.push(decl);
11211166 continue;
1122 } else if (decl.kind === 'const') {
1123 if (declTypeId === typeTypeId) {
1124 if (typeIsErrSet(declTypeId)) {
1167 }
1168
1169 if (decl.kind === 'const') {
1170 if (!("type" in declValue)){
1171 valsList.push(decl);
1172 } else {
1173 var value = zigAnalysis.types[declValue.type];
1174 var kind = value.kind;
1175 if (kind === typeKinds.Fn) {
1176 //if (allCompTimeFnCallsHaveTypeResult(decl.type, declTypeId)) {
1177 // typesList.push(decl);
1178 //} else {
1179 fnsList.push(decl);
1180 // }
1181
1182 } else if (typeIsErrSet(declValue.type)) {
11251183 errSetsList.push(decl);
1126 } else if (typeIsStructWithNoFields(declTypeId)) {
1184 } else if (typeIsStructWithNoFields(declValue.type)) {
11271185 namespacesList.push(decl);
11281186 } else {
11291187 typesList.push(decl);
11301188 }
1131 } else {
1132 var typeKind = zigAnalysis.types[declTypeId].kind;
1133 if (typeKind === typeKinds.Fn) {
1134 // TODO: this is broken but I don't understand functions yet
1135 if (allCompTimeFnCallsHaveTypeResult(decl.type, declTypeId)) {
1136 typesList.push(decl);
1137 } else {
1138 fnsList.push(decl);
1139 }
1140 } else {
1141 valsList.push(decl);
1142 }
11431189 }
11441190 }
11451191 }
......@@ -1202,7 +1248,10 @@
12021248 var tdFnCode = trDom.children[0];
12031249 var tdDesc = trDom.children[1];
12041250
1205 tdFnCode.innerHTML = typeIndexName(decl.type, true, true, decl, navLinkDecl(decl.name));
1251 var declType = resolveValue(decl.value);
1252 console.assert("type" in declType);
1253
1254 tdFnCode.innerHTML = typeIndexName(declType.type, true, true, decl, navLinkDecl(decl.name));
12061255
12071256 var docs = zigAnalysis.astNodes[decl.src].docs;
12081257 if (docs != null) {
......@@ -1238,11 +1287,7 @@
12381287 console.assert("type" in val);
12391288 var valType = zigAnalysis.types[val.type];
12401289
1241 var valTypeName = valType.name;
1242 if (valType.kind === typeKinds.Struct) {
1243 valTypeName = "struct";
1244 }
1245
1290 var valTypeName = typeShorthandName(valType);
12461291 html += '<a href="'+navLinkDecl(decl.name)+'">';
12471292 html += '<span class="tok-kw" style="color:lightblue;">' + decl.name + '</span>';
12481293 html += '</a>';
......@@ -1430,12 +1475,12 @@
14301475 function computeCanonicalPackagePaths() {
14311476 var list = new Array(zigAnalysis.packages.length);
14321477 // Now we try to find all the packages from root.
1433 var rootPkg = zigAnalysis.packages[zigAnalysis.rootPkg];
1478 var rootPkg = zigAnalysis.packages[zigAnalysis.rootPkg];
14341479 // Breadth-first to keep the path shortest possible.
1435 var stack = [{
1436 path: [],
1437 pkg: rootPkg,
1438 }];
1480 var stack = [{
1481 path: [],
1482 pkg: rootPkg,
1483 }];
14391484 while (stack.length !== 0) {
14401485 var item = stack.shift();
14411486 for (var key in item.pkg.table) {
......@@ -1534,7 +1579,7 @@
15341579
15351580 // PHASE 1:
15361581 // Dissect lines and determine the type for each line.
1537 // Also computes indentation level and removes unnecessary whitespace
1582 // Also computes indentation level and removes unnecessary whitespace
15381583
15391584 var is_reading_code = false;
15401585 var code_indent = 0;
......@@ -1613,20 +1658,20 @@
16131658
16141659 // PHASE 2:
16151660 // Render HTML from markdown lines.
1616 // Look at each line and emit fitting HTML code
1661 // Look at each line and emit fitting HTML code
16171662
16181663 function markdownInlines(innerText, stopChar) {
16191664
16201665 // inline types:
16211666 // **{INLINE}** : <strong>
1622 // __{INLINE}__ : <u>
1623 // ~~{INLINE}~~ : <s>
1624 // *{INLINE}* : <emph>
1625 // _{INLINE}_ : <emph>
1626 // `{TEXT}` : <code>
1627 // [{INLINE}]({URL}) : <a>
1628 // ![{TEXT}]({URL}) : <img>
1629 // [[std;format.fmt]] : <a> (inner link)
1667 // __{INLINE}__ : <u>
1668 // ~~{INLINE}~~ : <s>
1669 // *{INLINE}* : <emph>
1670 // _{INLINE}_ : <emph>
1671 // `{TEXT}` : <code>
1672 // [{INLINE}]({URL}) : <a>
1673 // ![{TEXT}]({URL}) : <img>
1674 // [[std;format.fmt]] : <a> (inner link)
16301675
16311676 const formats = [
16321677 {
......@@ -1668,9 +1713,9 @@
16681713 if (parsing_code && in_code) {
16691714 if (innerText.substr(i, codetag.length) == codetag) {
16701715 // remove leading and trailing whitespace if string both starts and ends with one.
1671 if (currentRun[0] == " " && currentRun[currentRun.length - 1] == " ") {
1672 currentRun = currentRun.substr(1, currentRun.length - 2);
1673 }
1716 if (currentRun[0] == " " && currentRun[currentRun.length - 1] == " ") {
1717 currentRun = currentRun.substr(1, currentRun.length - 2);
1718 }
16741719 flushRun();
16751720 i += codetag.length - 1;
16761721 in_code = false;
......@@ -1935,7 +1980,7 @@
19351980 startAsyncSearch();
19361981 break;
19371982 case "?":
1938 ev.preventDefault();
1983 ev.preventDefault();
19391984 ev.stopPropagation();
19401985 showHelpModal();
19411986 break;
......@@ -2054,60 +2099,60 @@
20542099 }
20552100 }
20562101
2057 function renderSearchCursor() {
2058 for (var i = 0; i < domListSearchResults.children.length; i += 1) {
2059 var liDom = domListSearchResults.children[i];
2060 if (curSearchIndex === i) {
2061 liDom.classList.add("selected");
2062 } else {
2063 liDom.classList.remove("selected");
2064 }
2102function renderSearchCursor() {
2103 for (var i = 0; i < domListSearchResults.children.length; i += 1) {
2104 var liDom = domListSearchResults.children[i];
2105 if (curSearchIndex === i) {
2106 liDom.classList.add("selected");
2107 } else {
2108 liDom.classList.remove("selected");
20652109 }
20662110 }
2111}
20672112
2068 function indexNodesToFns() {
2069 var map = {};
2070 for (var i = 0; i < zigAnalysis.fns.length; i += 1) {
2071 var fn = zigAnalysis.fns[i];
2072 if (typeIsGenericFn(fn.type)) continue;
2073 if (map[fn.src] == null) {
2074 map[fn.src] = [i];
2075 } else {
2076 map[fn.src].push(i);
2077 }
2113function indexNodesToFns() {
2114 var map = {};
2115 for (var i = 0; i < zigAnalysis.fns.length; i += 1) {
2116 var fn = zigAnalysis.fns[i];
2117 if (typeIsGenericFn(fn.type)) continue;
2118 if (map[fn.src] == null) {
2119 map[fn.src] = [i];
2120 } else {
2121 map[fn.src].push(i);
20782122 }
2079 return map;
20802123 }
2124 return map;
2125}
20812126
2082 function indexNodesToCalls() {
2083 var map = {};
2084 for (var i = 0; i < zigAnalysis.calls.length; i += 1) {
2085 var call = zigAnalysis.calls[i];
2086 var fn = zigAnalysis.fns[call.fn];
2087 if (map[fn.src] == null) {
2088 map[fn.src] = [i];
2089 } else {
2090 map[fn.src].push(i);
2091 }
2127function indexNodesToCalls() {
2128 var map = {};
2129 for (var i = 0; i < zigAnalysis.calls.length; i += 1) {
2130 var call = zigAnalysis.calls[i];
2131 var fn = zigAnalysis.fns[call.fn];
2132 if (map[fn.src] == null) {
2133 map[fn.src] = [i];
2134 } else {
2135 map[fn.src].push(i);
20922136 }
2093 return map;
20942137 }
2138 return map;
2139}
20952140
2096 function byNameProperty(a, b) {
2097 return operatorCompare(a.name, b.name);
2098 }
2141function byNameProperty(a, b) {
2142 return operatorCompare(a.name, b.name);
2143}
20992144
2100 function clone(obj) {
2101 var res = {};
2102 for (var key in obj) {
2103 res[key] = obj[key];
2104 }
2105 return res;
2145function clone(obj) {
2146 var res = {};
2147 for (var key in obj) {
2148 res[key] = obj[key];
21062149 }
2150 return res;
2151}
21072152
2108 function firstObjectKey(obj) {
2109 for (var key in obj) {
2110 return key;
2111 }
2153function firstObjectKey(obj) {
2154 for (var key in obj) {
2155 return key;
21122156 }
2157}
21132158})();