authorgravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2022-03-28 18:50:52+02:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2022-07-19 19:10:11-07:00
log53fa75c8522be655ea2cdeec3cf8bc0d6380a532
tree78b7690dac3a40f933252ecfd972756e5042b0b3
parent36c4b1aac995a5b0ef273c02c0b2c0271cab6b94

autodoc: improved frontend rendering

3 files changed, 93 insertions(+), 18 deletions(-)

lib/docs/index.html+9-1
...@@ -634,7 +634,15 @@...@@ -634,7 +634,15 @@
634 <h2>Examples</h2>634 <h2>Examples</h2>
635 <ul id="listFnExamples" class="examples"></ul>635 <ul id="listFnExamples" class="examples"></ul>
636 </div>636 </div>
637 </section>637 <div id="sectTests" class="hidden">
638 <h2>Tests</h2>
639 <div class="table-container">
640 <table>
641 <tbody id="listTests"></tbody>
642 </table>
643 </div>
644 </div>
645 </section>
638 </div>646 </div>
639 <div class="flex-filler"></div>647 <div class="flex-filler"></div>
640 </div>648 </div>
lib/docs/main.js+69-11
...@@ -176,6 +176,8 @@ var zigAnalysis;...@@ -176,6 +176,8 @@ var zigAnalysis;
176 var domListPkgs = document.getElementById("listPkgs");176 var domListPkgs = document.getElementById("listPkgs");
177 var domSectTypes = document.getElementById("sectTypes");177 var domSectTypes = document.getElementById("sectTypes");
178 var domListTypes = document.getElementById("listTypes");178 var domListTypes = document.getElementById("listTypes");
179 var domSectTests = document.getElementById("sectTests");
180 var domListTests = document.getElementById("listTests");
179 var domSectNamespaces = document.getElementById("sectNamespaces");181 var domSectNamespaces = document.getElementById("sectNamespaces");
180 var domListNamespaces = document.getElementById("listNamespaces");182 var domListNamespaces = document.getElementById("listNamespaces");
181 var domSectErrSets = document.getElementById("sectErrSets");183 var domSectErrSets = document.getElementById("sectErrSets");
...@@ -349,6 +351,7 @@ var zigAnalysis;...@@ -349,6 +351,7 @@ var zigAnalysis;
349351
350 if ("declRef" in value) {352 if ("declRef" in value) {
351 value = zigAnalysis.decls[value.declRef].value;353 value = zigAnalysis.decls[value.declRef].value;
354 continue;
352 }355 }
353356
354 return value;357 return value;
...@@ -439,6 +442,7 @@ var zigAnalysis;...@@ -439,6 +442,7 @@ var zigAnalysis;
439 domSectMainPkg.classList.add("hidden");442 domSectMainPkg.classList.add("hidden");
440 domSectPkgs.classList.add("hidden");443 domSectPkgs.classList.add("hidden");
441 domSectTypes.classList.add("hidden");444 domSectTypes.classList.add("hidden");
445 domSectTests.classList.add("hidden");
442 domSectNamespaces.classList.add("hidden");446 domSectNamespaces.classList.add("hidden");
443 domSectErrSets.classList.add("hidden");447 domSectErrSets.classList.add("hidden");
444 domSectFns.classList.add("hidden");448 domSectFns.classList.add("hidden");
...@@ -845,10 +849,10 @@ var zigAnalysis;...@@ -845,10 +849,10 @@ var zigAnalysis;
845 if ("call" in typeValue) {849 if ("call" in typeValue) {
846 var result = "";850 var result = "";
847 var call = zigAnalysis.calls[typeValue.call];851 var call = zigAnalysis.calls[typeValue.call];
848 var functionName = typeValueName(call.func);852 var functionName = typeValueName(call.func, wantHtml, wantLink, fnDecl, linkFnNameDecl);
849 result += functionName + "(";853 result += functionName + "(";
850 for (var j = 0; j < call.args.length; j += 1) {854 for (var j = 0; j < call.args.length; j += 1) {
851 result += typeValueName(call.args[j]);855 result += typeValueName(call.args[j], wantHtml, wantLink, fnDecl, linkFnNameDecl);
852 if (j != call.args.length -1) result += ",";856 if (j != call.args.length -1) result += ",";
853 }857 }
854858
...@@ -878,6 +882,22 @@ var zigAnalysis;...@@ -878,6 +882,22 @@ var zigAnalysis;
878 return result;882 return result;
879 }883 }
880884
885 if ("declRef" in typeValue) {
886 return zigAnalysis.decls[typeValue.declRef].name;
887 }
888
889 if ("string" in typeValue) {
890 return typeValue.string + " (string)";
891 }
892
893 if ("anytype" in typeValue) {
894 return "anytype";
895 }
896
897 if ("this" in typeValue) {
898 return "this";
899 }
900
881 console.assert("type" in typeValue)901 console.assert("type" in typeValue)
882 var typeIndex = typeValue.type;902 var typeIndex = typeValue.type;
883 var typeObj = zigAnalysis.types[typeIndex];903 var typeObj = zigAnalysis.types[typeIndex];
...@@ -1133,7 +1153,7 @@ var zigAnalysis;...@@ -1133,7 +1153,7 @@ var zigAnalysis;
1133 if (typeObj.params) {1153 if (typeObj.params) {
1134 var fields = null;1154 var fields = null;
1135 var isVarArgs = false;1155 var isVarArgs = false;
1136 var fnNode = zigAnalysis.astNodes[fnDecl.src];1156 var fnNode = zigAnalysis.astNodes[typeObj.src];
1137 fields = fnNode.fields;1157 fields = fnNode.fields;
1138 isVarArgs = fnNode.varArgs;1158 isVarArgs = fnNode.varArgs;
11391159
...@@ -1411,12 +1431,17 @@ var zigAnalysis;...@@ -1411,12 +1431,17 @@ var zigAnalysis;
14111431
1412 function categorizeDecls(decls,1432 function categorizeDecls(decls,
1413 typesList, namespacesList, errSetsList,1433 typesList, namespacesList, errSetsList,
1414 fnsList, varsList, valsList) {1434 fnsList, varsList, valsList, testsList) {
14151435
1416 for (var i = 0; i < decls.length; i += 1) {1436 for (var i = 0; i < decls.length; i += 1) {
1417 var decl = zigAnalysis.decls[decls[i]];1437 var decl = zigAnalysis.decls[decls[i]];
1418 var declValue = resolveValue(decl.value);1438 var declValue = resolveValue(decl.value);
14191439
1440 if (decl.isTest) {
1441 testsList.push(decl);
1442 continue;
1443 }
1444
1420 if (decl.kind === 'var') {1445 if (decl.kind === 'var') {
1421 varsList.push(decl);1446 varsList.push(decl);
1422 continue;1447 continue;
...@@ -1427,11 +1452,15 @@ var zigAnalysis;...@@ -1427,11 +1452,15 @@ var zigAnalysis;
1427 let c = zigAnalysis.calls[declValue.call];1452 let c = zigAnalysis.calls[declValue.call];
1428 console.assert("comptimeExpr" in c.ret);1453 console.assert("comptimeExpr" in c.ret);
1429 let fDecl = resolveValue(c.func);1454 let fDecl = resolveValue(c.func);
1430 console.assert("type" in fDecl);1455 if ("type" in fDecl) {
1431 let fType = zigAnalysis.types[fDecl.type];1456 console.assert("type" in fDecl);
1432 console.assert("type" in fType.ret);1457 let fType = zigAnalysis.types[fDecl.type];
1433 if (fType.ret.type === typeTypeId) {1458 console.assert("type" in fType.ret);
1434 typesList.push(decl);1459 if (fType.ret.type === typeTypeId) {
1460 typesList.push(decl);
1461 } else {
1462 valsList.push(decl);
1463 }
1435 } else {1464 } else {
1436 valsList.push(decl);1465 valsList.push(decl);
1437 }1466 }
...@@ -1468,13 +1497,14 @@ var zigAnalysis;...@@ -1468,13 +1497,14 @@ var zigAnalysis;
1468 var fnsList = [];1497 var fnsList = [];
1469 var varsList = [];1498 var varsList = [];
1470 var valsList = [];1499 var valsList = [];
1500 var testsList = [];
14711501
1472 categorizeDecls(container.pubDecls,1502 categorizeDecls(container.pubDecls,
1473 typesList, namespacesList, errSetsList,1503 typesList, namespacesList, errSetsList,
1474 fnsList, varsList, valsList);1504 fnsList, varsList, valsList, testsList);
1475 if (curNav.showPrivDecls) categorizeDecls(container.privDecls,1505 if (curNav.showPrivDecls) categorizeDecls(container.privDecls,
1476 typesList, namespacesList, errSetsList,1506 typesList, namespacesList, errSetsList,
1477 fnsList, varsList, valsList);1507 fnsList, varsList, valsList, testsList);
14781508
14791509
1480 typesList.sort(byNameProperty);1510 typesList.sort(byNameProperty);
...@@ -1483,6 +1513,7 @@ var zigAnalysis;...@@ -1483,6 +1513,7 @@ var zigAnalysis;
1483 fnsList.sort(byNameProperty);1513 fnsList.sort(byNameProperty);
1484 varsList.sort(byNameProperty);1514 varsList.sort(byNameProperty);
1485 valsList.sort(byNameProperty);1515 valsList.sort(byNameProperty);
1516 testsList.sort(byNameProperty);
14861517
1487 if (container.src != null) {1518 if (container.src != null) {
1488 var docs = zigAnalysis.astNodes[container.src].docs;1519 var docs = zigAnalysis.astNodes[container.src].docs;
...@@ -1638,6 +1669,33 @@ var zigAnalysis;...@@ -1638,6 +1669,33 @@ var zigAnalysis;
1638 }1669 }
1639 domSectValues.classList.remove("hidden");1670 domSectValues.classList.remove("hidden");
1640 }1671 }
1672
1673 if (testsList.length !== 0) {
1674 resizeDomList(domListTests, testsList.length,
1675 '<tr><td><a href="#"></a></td><td></td><td></td></tr>');
1676 for (var i = 0; i < testsList.length; i += 1) {
1677 var decl = testsList[i];
1678 var trDom = domListTests.children[i];
1679
1680 var tdName = trDom.children[0];
1681 var tdNameA = tdName.children[0];
1682 var tdType = trDom.children[1];
1683 var tdDesc = trDom.children[2];
1684
1685 tdNameA.setAttribute('href', navLinkDecl(decl.name));
1686 tdNameA.textContent = decl.name;
1687
1688 tdType.innerHTML = typeValueName(typeOfDecl(decl), true, true);
1689
1690 var docs = zigAnalysis.astNodes[decl.src].docs;
1691 if (docs != null) {
1692 tdDesc.innerHTML = shortDescMarkdown(docs);
1693 } else {
1694 tdDesc.textContent = "";
1695 }
1696 }
1697 domSectTests.classList.remove("hidden");
1698 }
1641 }1699 }
16421700
1643 function operatorCompare(a, b) {1701 function operatorCompare(a, b) {
src/Autodoc.zig+15-6
...@@ -354,6 +354,7 @@ const DocData = struct {...@@ -354,6 +354,7 @@ const DocData = struct {
354 const Decl = struct {354 const Decl = struct {
355 name: []const u8,355 name: []const u8,
356 kind: []const u8,356 kind: []const u8,
357 isTest: bool,
357 src: usize, // index into astNodes358 src: usize, // index into astNodes
358 // typeRef: TypeRef,359 // typeRef: TypeRef,
359 value: WalkResult,360 value: WalkResult,
...@@ -621,7 +622,6 @@ const DocData = struct {...@@ -621,7 +622,6 @@ const DocData = struct {
621 .@"undefined" => |v| try std.json.stringify(v, options, w),622 .@"undefined" => |v| try std.json.stringify(v, options, w),
622 .@"null" => |v| try std.json.stringify(v, options, w),623 .@"null" => |v| try std.json.stringify(v, options, w),
623 .typeOf, .sizeOf => |v| try std.json.stringify(v, options, w),624 .typeOf, .sizeOf => |v| try std.json.stringify(v, options, w),
624 .compileError => |v| try std.json.stringify(v, options, w),
625 .fieldRef => |v| try std.json.stringify(625 .fieldRef => |v| try std.json.stringify(
626 struct { fieldRef: FieldRef }{ .fieldRef = v },626 struct { fieldRef: FieldRef }{ .fieldRef = v },
627 options,627 options,
...@@ -645,6 +645,11 @@ const DocData = struct {...@@ -645,6 +645,11 @@ const DocData = struct {
645 options,645 options,
646 w,646 w,
647 ),647 ),
648 .compileError => |v| try std.json.stringify(
649 struct { compileError: []const u8 }{ .compileError = v },
650 options,
651 w,
652 ),
648 .string => |v| try std.json.stringify(653 .string => |v| try std.json.stringify(
649 struct { string: []const u8 }{ .string = v },654 struct { string: []const u8 }{ .string = v },
650 options,655 options,
...@@ -1678,7 +1683,7 @@ fn walkDecls(...@@ -1678,7 +1683,7 @@ fn walkDecls(
1678 extra_index += 1;1683 extra_index += 1;
1679 const decl_name_index = file.zir.extra[extra_index];1684 const decl_name_index = file.zir.extra[extra_index];
1680 extra_index += 1;1685 extra_index += 1;
1681 const decl_index = file.zir.extra[extra_index];1686 const value_index = file.zir.extra[extra_index];
1682 extra_index += 1;1687 extra_index += 1;
1683 const doc_comment_index = file.zir.extra[extra_index];1688 const doc_comment_index = file.zir.extra[extra_index];
1684 extra_index += 1;1689 extra_index += 1;
...@@ -1722,7 +1727,7 @@ fn walkDecls(...@@ -1722,7 +1727,7 @@ fn walkDecls(
1722 const idx = self.ast_nodes.items.len;1727 const idx = self.ast_nodes.items.len;
1723 const file_source = file.getSource(self.module.gpa) catch unreachable; // TODO fix this1728 const file_source = file.getSource(self.module.gpa) catch unreachable; // TODO fix this
1724 const source_of_decltest_function = srcloc: {1729 const source_of_decltest_function = srcloc: {
1725 const func_index = getBlockInlineBreak(file.zir, decl_index);1730 const func_index = getBlockInlineBreak(file.zir, value_index);
1726 // a decltest is always a function1731 // a decltest is always a function
1727 const tag = file.zir.instructions.items(.tag)[Zir.refToIndex(func_index).?];1732 const tag = file.zir.instructions.items(.tag)[Zir.refToIndex(func_index).?];
1728 std.debug.assert(tag == .extended);1733 std.debug.assert(tag == .extended);
...@@ -1785,6 +1790,7 @@ fn walkDecls(...@@ -1785,6 +1790,7 @@ fn walkDecls(
1785 self.decls.items[decls_slot_index] = .{1790 self.decls.items[decls_slot_index] = .{
1786 ._analyzed = true,1791 ._analyzed = true,
1787 .name = "test",1792 .name = "test",
1793 .isTest = true,
1788 .src = ast_node_index,1794 .src = ast_node_index,
1789 .value = .{ .type = 0 },1795 .value = .{ .type = 0 },
1790 .kind = "const",1796 .kind = "const",
...@@ -1822,7 +1828,7 @@ fn walkDecls(...@@ -1822,7 +1828,7 @@ fn walkDecls(
1822 const walk_result = if (is_test) // TODO: decide if tests should show up at all1828 const walk_result = if (is_test) // TODO: decide if tests should show up at all
1823 DocData.WalkResult{ .void = {} }1829 DocData.WalkResult{ .void = {} }
1824 else1830 else
1825 try self.walkInstruction(file, scope, decl_index);1831 try self.walkInstruction(file, scope, value_index);
18261832
1827 if (is_pub) {1833 if (is_pub) {
1828 try decl_indexes.append(self.arena, decls_slot_index);1834 try decl_indexes.append(self.arena, decls_slot_index);
...@@ -1848,6 +1854,7 @@ fn walkDecls(...@@ -1848,6 +1854,7 @@ fn walkDecls(
1848 self.decls.items[decls_slot_index] = .{1854 self.decls.items[decls_slot_index] = .{
1849 ._analyzed = true,1855 ._analyzed = true,
1850 .name = name,1856 .name = name,
1857 .isTest = is_test,
1851 .src = ast_node_index,1858 .src = ast_node_index,
1852 // .typeRef = decl_type_ref,1859 // .typeRef = decl_type_ref,
1853 .value = walk_result,1860 .value = walk_result,
...@@ -1859,7 +1866,7 @@ fn walkDecls(...@@ -1859,7 +1866,7 @@ fn walkDecls(
1859 for (paths.items) |resume_info| {1866 for (paths.items) |resume_info| {
1860 try self.tryResolveRefPath(1867 try self.tryResolveRefPath(
1861 resume_info.file,1868 resume_info.file,
1862 decl_index,1869 value_index,
1863 resume_info.ref_path,1870 resume_info.ref_path,
1864 );1871 );
1865 }1872 }
...@@ -2283,7 +2290,7 @@ fn analyzeFunction(...@@ -2283,7 +2290,7 @@ fn analyzeFunction(
2283 .ret = ret_type_ref,2290 .ret = ret_type_ref,
2284 },2291 },
2285 };2292 };
2286 return DocData.WalkResult{ .type = self.types.items.len - 1 };2293 return DocData.WalkResult{ .type = type_slot_index };
2287}2294}
22882295
2289fn collectUnionFieldInfo(2296fn collectUnionFieldInfo(
...@@ -2553,10 +2560,12 @@ fn typeOfWalkResult(self: *Autodoc, wr: DocData.WalkResult) !DocData.WalkResult...@@ -2553,10 +2560,12 @@ fn typeOfWalkResult(self: *Autodoc, wr: DocData.WalkResult) !DocData.WalkResult
2553}2560}
25542561
2555fn getBlockInlineBreak(zir: Zir, inst_index: usize) Zir.Inst.Ref {2562fn getBlockInlineBreak(zir: Zir, inst_index: usize) Zir.Inst.Ref {
2563 const tags = zir.instructions.items(.tag);
2556 const data = zir.instructions.items(.data);2564 const data = zir.instructions.items(.data);
2557 const pl_node = data[inst_index].pl_node;2565 const pl_node = data[inst_index].pl_node;
2558 const extra = zir.extraData(Zir.Inst.Block, pl_node.payload_index);2566 const extra = zir.extraData(Zir.Inst.Block, pl_node.payload_index);
2559 const break_index = zir.extra[extra.end..][extra.data.body_len - 1];2567 const break_index = zir.extra[extra.end..][extra.data.body_len - 1];
2568 std.debug.assert(tags[break_index] == .break_inline);
2560 return data[break_index].@"break".operand;2569 return data[break_index].@"break".operand;
2561}2570}
25622571