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 @@
634634 <h2>Examples</h2>
635635 <ul id="listFnExamples" class="examples"></ul>
636636 </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>
638646 </div>
639647 <div class="flex-filler"></div>
640648 </div>
lib/docs/main.js+69-11
......@@ -176,6 +176,8 @@ var zigAnalysis;
176176 var domListPkgs = document.getElementById("listPkgs");
177177 var domSectTypes = document.getElementById("sectTypes");
178178 var domListTypes = document.getElementById("listTypes");
179 var domSectTests = document.getElementById("sectTests");
180 var domListTests = document.getElementById("listTests");
179181 var domSectNamespaces = document.getElementById("sectNamespaces");
180182 var domListNamespaces = document.getElementById("listNamespaces");
181183 var domSectErrSets = document.getElementById("sectErrSets");
......@@ -349,6 +351,7 @@ var zigAnalysis;
349351
350352 if ("declRef" in value) {
351353 value = zigAnalysis.decls[value.declRef].value;
354 continue;
352355 }
353356
354357 return value;
......@@ -439,6 +442,7 @@ var zigAnalysis;
439442 domSectMainPkg.classList.add("hidden");
440443 domSectPkgs.classList.add("hidden");
441444 domSectTypes.classList.add("hidden");
445 domSectTests.classList.add("hidden");
442446 domSectNamespaces.classList.add("hidden");
443447 domSectErrSets.classList.add("hidden");
444448 domSectFns.classList.add("hidden");
......@@ -845,10 +849,10 @@ var zigAnalysis;
845849 if ("call" in typeValue) {
846850 var result = "";
847851 var call = zigAnalysis.calls[typeValue.call];
848 var functionName = typeValueName(call.func);
852 var functionName = typeValueName(call.func, wantHtml, wantLink, fnDecl, linkFnNameDecl);
849853 result += functionName + "(";
850854 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);
852856 if (j != call.args.length -1) result += ",";
853857 }
854858
......@@ -878,6 +882,22 @@ var zigAnalysis;
878882 return result;
879883 }
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
881901 console.assert("type" in typeValue)
882902 var typeIndex = typeValue.type;
883903 var typeObj = zigAnalysis.types[typeIndex];
......@@ -1133,7 +1153,7 @@ var zigAnalysis;
11331153 if (typeObj.params) {
11341154 var fields = null;
11351155 var isVarArgs = false;
1136 var fnNode = zigAnalysis.astNodes[fnDecl.src];
1156 var fnNode = zigAnalysis.astNodes[typeObj.src];
11371157 fields = fnNode.fields;
11381158 isVarArgs = fnNode.varArgs;
11391159
......@@ -1411,12 +1431,17 @@ var zigAnalysis;
14111431
14121432 function categorizeDecls(decls,
14131433 typesList, namespacesList, errSetsList,
1414 fnsList, varsList, valsList) {
1434 fnsList, varsList, valsList, testsList) {
14151435
14161436 for (var i = 0; i < decls.length; i += 1) {
14171437 var decl = zigAnalysis.decls[decls[i]];
14181438 var declValue = resolveValue(decl.value);
14191439
1440 if (decl.isTest) {
1441 testsList.push(decl);
1442 continue;
1443 }
1444
14201445 if (decl.kind === 'var') {
14211446 varsList.push(decl);
14221447 continue;
......@@ -1427,11 +1452,15 @@ var zigAnalysis;
14271452 let c = zigAnalysis.calls[declValue.call];
14281453 console.assert("comptimeExpr" in c.ret);
14291454 let fDecl = resolveValue(c.func);
1430 console.assert("type" in fDecl);
1431 let fType = zigAnalysis.types[fDecl.type];
1432 console.assert("type" in fType.ret);
1433 if (fType.ret.type === typeTypeId) {
1434 typesList.push(decl);
1455 if ("type" in fDecl) {
1456 console.assert("type" in fDecl);
1457 let fType = zigAnalysis.types[fDecl.type];
1458 console.assert("type" in fType.ret);
1459 if (fType.ret.type === typeTypeId) {
1460 typesList.push(decl);
1461 } else {
1462 valsList.push(decl);
1463 }
14351464 } else {
14361465 valsList.push(decl);
14371466 }
......@@ -1468,13 +1497,14 @@ var zigAnalysis;
14681497 var fnsList = [];
14691498 var varsList = [];
14701499 var valsList = [];
1500 var testsList = [];
14711501
14721502 categorizeDecls(container.pubDecls,
14731503 typesList, namespacesList, errSetsList,
1474 fnsList, varsList, valsList);
1504 fnsList, varsList, valsList, testsList);
14751505 if (curNav.showPrivDecls) categorizeDecls(container.privDecls,
14761506 typesList, namespacesList, errSetsList,
1477 fnsList, varsList, valsList);
1507 fnsList, varsList, valsList, testsList);
14781508
14791509
14801510 typesList.sort(byNameProperty);
......@@ -1483,6 +1513,7 @@ var zigAnalysis;
14831513 fnsList.sort(byNameProperty);
14841514 varsList.sort(byNameProperty);
14851515 valsList.sort(byNameProperty);
1516 testsList.sort(byNameProperty);
14861517
14871518 if (container.src != null) {
14881519 var docs = zigAnalysis.astNodes[container.src].docs;
......@@ -1638,6 +1669,33 @@ var zigAnalysis;
16381669 }
16391670 domSectValues.classList.remove("hidden");
16401671 }
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 }
16411699 }
16421700
16431701 function operatorCompare(a, b) {
src/Autodoc.zig+15-6
......@@ -354,6 +354,7 @@ const DocData = struct {
354354 const Decl = struct {
355355 name: []const u8,
356356 kind: []const u8,
357 isTest: bool,
357358 src: usize, // index into astNodes
358359 // typeRef: TypeRef,
359360 value: WalkResult,
......@@ -621,7 +622,6 @@ const DocData = struct {
621622 .@"undefined" => |v| try std.json.stringify(v, options, w),
622623 .@"null" => |v| try std.json.stringify(v, options, w),
623624 .typeOf, .sizeOf => |v| try std.json.stringify(v, options, w),
624 .compileError => |v| try std.json.stringify(v, options, w),
625625 .fieldRef => |v| try std.json.stringify(
626626 struct { fieldRef: FieldRef }{ .fieldRef = v },
627627 options,
......@@ -645,6 +645,11 @@ const DocData = struct {
645645 options,
646646 w,
647647 ),
648 .compileError => |v| try std.json.stringify(
649 struct { compileError: []const u8 }{ .compileError = v },
650 options,
651 w,
652 ),
648653 .string => |v| try std.json.stringify(
649654 struct { string: []const u8 }{ .string = v },
650655 options,
......@@ -1678,7 +1683,7 @@ fn walkDecls(
16781683 extra_index += 1;
16791684 const decl_name_index = file.zir.extra[extra_index];
16801685 extra_index += 1;
1681 const decl_index = file.zir.extra[extra_index];
1686 const value_index = file.zir.extra[extra_index];
16821687 extra_index += 1;
16831688 const doc_comment_index = file.zir.extra[extra_index];
16841689 extra_index += 1;
......@@ -1722,7 +1727,7 @@ fn walkDecls(
17221727 const idx = self.ast_nodes.items.len;
17231728 const file_source = file.getSource(self.module.gpa) catch unreachable; // TODO fix this
17241729 const source_of_decltest_function = srcloc: {
1725 const func_index = getBlockInlineBreak(file.zir, decl_index);
1730 const func_index = getBlockInlineBreak(file.zir, value_index);
17261731 // a decltest is always a function
17271732 const tag = file.zir.instructions.items(.tag)[Zir.refToIndex(func_index).?];
17281733 std.debug.assert(tag == .extended);
......@@ -1785,6 +1790,7 @@ fn walkDecls(
17851790 self.decls.items[decls_slot_index] = .{
17861791 ._analyzed = true,
17871792 .name = "test",
1793 .isTest = true,
17881794 .src = ast_node_index,
17891795 .value = .{ .type = 0 },
17901796 .kind = "const",
......@@ -1822,7 +1828,7 @@ fn walkDecls(
18221828 const walk_result = if (is_test) // TODO: decide if tests should show up at all
18231829 DocData.WalkResult{ .void = {} }
18241830 else
1825 try self.walkInstruction(file, scope, decl_index);
1831 try self.walkInstruction(file, scope, value_index);
18261832
18271833 if (is_pub) {
18281834 try decl_indexes.append(self.arena, decls_slot_index);
......@@ -1848,6 +1854,7 @@ fn walkDecls(
18481854 self.decls.items[decls_slot_index] = .{
18491855 ._analyzed = true,
18501856 .name = name,
1857 .isTest = is_test,
18511858 .src = ast_node_index,
18521859 // .typeRef = decl_type_ref,
18531860 .value = walk_result,
......@@ -1859,7 +1866,7 @@ fn walkDecls(
18591866 for (paths.items) |resume_info| {
18601867 try self.tryResolveRefPath(
18611868 resume_info.file,
1862 decl_index,
1869 value_index,
18631870 resume_info.ref_path,
18641871 );
18651872 }
......@@ -2283,7 +2290,7 @@ fn analyzeFunction(
22832290 .ret = ret_type_ref,
22842291 },
22852292 };
2286 return DocData.WalkResult{ .type = self.types.items.len - 1 };
2293 return DocData.WalkResult{ .type = type_slot_index };
22872294}
22882295
22892296fn collectUnionFieldInfo(
......@@ -2553,10 +2560,12 @@ fn typeOfWalkResult(self: *Autodoc, wr: DocData.WalkResult) !DocData.WalkResult
25532560}
25542561
25552562fn getBlockInlineBreak(zir: Zir, inst_index: usize) Zir.Inst.Ref {
2563 const tags = zir.instructions.items(.tag);
25562564 const data = zir.instructions.items(.data);
25572565 const pl_node = data[inst_index].pl_node;
25582566 const extra = zir.extraData(Zir.Inst.Block, pl_node.payload_index);
25592567 const break_index = zir.extra[extra.end..][extra.data.body_len - 1];
2568 std.debug.assert(tags[break_index] == .break_inline);
25602569 return data[break_index].@"break".operand;
25612570}
25622571