authorgravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2022-02-08 20:56:12+01:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2022-07-19 19:10:10-07:00
logb296f5ac023517a4cbf31abdab52cabcc2d3c1e7
tree075c8d84ccc4229de55a676e6707211e285700dd
parent5a31126d897e58b87fea1c709696b44959cf1021

autodocs: added basic support for functions

2 files changed, 68 insertions(+), 48 deletions(-)

lib/docs/main.js+44-43
......@@ -130,17 +130,17 @@
130130 return typeKind === typeKinds.ErrorSet || typeKindIsContainer(typeKind);
131131 }
132132
133 function resolveDeclValue(decl) {
133 function resolveValue(value) {
134134 var i = 0;
135135 while(i < 1000) {
136136 i += 1;
137137
138 if ("declRef" in decl.value) {
139 decl = zigAnalysis.decls[decl.value.declRef];
138 if ("declRef" in value) {
139 value = zigAnalysis.decls[value.declRef].value;
140140 continue;
141141 }
142142
143 return decl.value;
143 return value;
144144
145145 }
146146 console.assert(false);
......@@ -249,8 +249,9 @@
249249 return render404();
250250 }
251251
252 var childDeclValue = resolveDeclValue(childDecl);
253 if ("type" in childDeclValue){
252 var childDeclValue = resolveValue(childDecl.value);
253 if ("type" in childDeclValue &&
254 zigAnalysis.types[childDeclValue.type].kind !== typeKinds.Fn){
254255 if (i + 1 === curNav.declNames.length) {
255256 curNav.declObjs.push(zigAnalysis.types[childDeclValue.type]);
256257 break;
......@@ -277,7 +278,7 @@
277278 } else if (lastIsDecl && last.kind === 'var') {
278279 return renderVar(last);
279280 } else if (lastIsDecl && last.kind === 'const' && !(declContainsType(last))) {
280 var typeObj = zigAnalysis.types[resolveDeclValueTypeId(last)];
281 var typeObj = zigAnalysis.types[resolveValue(last.value).type];
281282 if (typeObj.kind === typeKinds.Fn) {
282283 return renderFn(last);
283284 } else {
......@@ -321,7 +322,11 @@
321322 }
322323
323324 function renderFn(fnDecl) {
324 domFnProtoCode.innerHTML = typeIndexName(fnDecl.type, true, true, fnDecl);
325 var value = resolveValue(fnDecl.value);
326 console.assert("type" in value);
327 var typeObj = zigAnalysis.types[value.type];
328
329 domFnProtoCode.innerHTML = typeIndexName(value.type, true, true, fnDecl);
325330
326331 var docsSource = null;
327332 var srcNode = zigAnalysis.astNodes[fnDecl.src];
......@@ -329,26 +334,23 @@
329334 docsSource = srcNode.docs;
330335 }
331336
332 var typeObj = zigAnalysis.types[fnDecl.type];
337 var retIndex = resolveValue(typeObj.ret).type;
333338 renderFnParamDocs(fnDecl, typeObj);
334339
335340 var errSetTypeIndex = null;
336 if (typeObj.ret != null) {
337 var retType = zigAnalysis.types[typeObj.ret];
338 if (retType.kind === typeKinds.ErrorSet) {
339 errSetTypeIndex = typeObj.ret;
340 } else if (retType.kind === typeKinds.ErrorUnion) {
341 errSetTypeIndex = retType.err;
342 }
341 var retType = zigAnalysis.types[retIndex];
342 if (retType.kind === typeKinds.ErrorSet) {
343 errSetTypeIndex = retIndex;
344 } else if (retType.kind === typeKinds.ErrorUnion) {
345 errSetTypeIndex = retType.err;
343346 }
344347 if (errSetTypeIndex != null) {
345348 var errSetType = zigAnalysis.types[errSetTypeIndex];
346349 renderErrorSet(errSetType);
347350 }
348351
349 var fnObj = zigAnalysis.fns[fnDecl.value];
350 var protoSrcIndex = fnObj.src;
351 if (typeIsGenericFn(fnDecl.type)) {
352 var protoSrcIndex = fnDecl.src;
353 if (typeIsGenericFn(value.type)) {
352354 var instantiations = nodesToFnsMap[protoSrcIndex];
353355 var calls = nodesToCallsMap[protoSrcIndex];
354356 if (instantiations == null && calls == null) {
......@@ -388,8 +390,7 @@
388390 function renderFnParamDocs(fnDecl, typeObj) {
389391 var docCount = 0;
390392
391 var fnObj = zigAnalysis.fns[fnDecl.value];
392 var fnNode = zigAnalysis.astNodes[fnObj.src];
393 var fnNode = zigAnalysis.astNodes[fnDecl.src];
393394 var fields = fnNode.fields;
394395 var isVarArgs = fnNode.varArgs;
395396
......@@ -415,10 +416,11 @@
415416 }
416417 var divDom = domListParams.children[domIndex];
417418 domIndex += 1;
418 var argTypeIndex = typeObj.args[i];
419
419 var value = resolveValue(typeObj.params[i]);
420 console.assert("type" in value);
421 var argTypeIndex = value.type;
420422 var html = '<pre>' + escapeHtml(fieldNode.name) + ": ";
421 if (isVarArgs && i === typeObj.args.length - 1) {
423 if (isVarArgs && i === typeObj.params.length - 1) {
422424 html += '...';
423425 } else if (argTypeIndex != null) {
424426 html += typeIndexName(argTypeIndex, true, true);
......@@ -741,11 +743,7 @@
741743 return "f" + typeObj.bits;
742744 }
743745 case typeKinds.Int:
744 var signed = (typeObj.i != null) ? 'i' : 'u';
745 var bits = typeObj[signed] || typeObj.name;
746
747 var name = typeObj.name ? typeObj.name : signed + bits;
748
746 var name = typeObj.name;
749747 if (wantHtml) {
750748 return '<span class="tok-type">' + name + '</span>';
751749 } else {
......@@ -834,22 +832,21 @@
834832 payloadHtml += 'fn'
835833 }
836834 payloadHtml += '(';
837 if (typeObj.args != null) {
835 if (typeObj.params) {
838836 var fields = null;
839837 var isVarArgs = false;
840 if (fnDecl != null) {
841 var fnObj = zigAnalysis.fns[fnDecl.value];
842 var fnNode = zigAnalysis.astNodes[fnObj.src];
843 fields = fnNode.fields;
844 isVarArgs = fnNode.varArgs;
845 }
838 var fnNode = zigAnalysis.astNodes[fnDecl.src];
839 fields = fnNode.fields;
840 isVarArgs = fnNode.varArgs;
846841
847 for (var i = 0; i < typeObj.args.length; i += 1) {
842 for (var i = 0; i < typeObj.params.length; i += 1) {
848843 if (i != 0) {
849844 payloadHtml += ', ';
850845 }
851846
852 var argTypeIndex = typeObj.args[i];
847 var paramValue = resolveValue(typeObj.params[i]);
848 console.assert("type" in paramValue);
849 var argTypeIndex = paramValue.type;
853850
854851 if (fields != null) {
855852 var paramNode = zigAnalysis.astNodes[fields[i]];
......@@ -896,13 +893,17 @@
896893 }
897894 }
898895
896 var retValue = resolveValue(typeObj.ret);
897 console.assert("type" in retValue);
898 var retTypeIndex = retValue.type;
899
899900 payloadHtml += ') ';
900 if (typeObj.ret != null) {
901 payloadHtml += typeIndexName(typeObj.ret, wantHtml, wantSubLink, fnDecl);
901 if (retTypeIndex != null) {
902 payloadHtml += typeIndexName(retTypeIndex, wantHtml, wantSubLink, fnDecl);
902903 } else if (wantHtml) {
903 payloadHtml += '<span class="tok-kw">var</span>';
904 payloadHtml += '<span class="tok-kw">anytype</span>';
904905 } else {
905 payloadHtml += 'var';
906 payloadHtml += 'anytype';
906907 }
907908 return payloadHtml;
908909 default:
......@@ -1233,7 +1234,7 @@
12331234 html += '<span class="tok-kw" style="color:red;">#FAILURE#</span>';
12341235 } else if ("declRef" in field) {
12351236 var decl = zigAnalysis.decls[field.declRef];
1236 var val = resolveDeclValue(decl);
1237 var val = resolveValue(decl.value);
12371238 console.assert("type" in val);
12381239 var valType = zigAnalysis.types[val.type];
12391240
src/Autodoc.zig+24-5
......@@ -560,6 +560,13 @@ fn walkInstruction(
560560 });
561561 return DocData.WalkResult{ .type = self.types.items.len - 1 };
562562 },
563 //.block => {
564 //const pl_node = data[inst_index].pl_node;
565 //const extra = zir.extraData(Zir.Inst.Block, pl_node.payload_index);
566 //const last_instr_index = zir.extra[extra.end..][extra.data.body_len - 1];
567 //const break_operand = data[break_index].@"break".operand;
568 //return self.walkRef(zir, parent_scope, break_operand);
569 //},
563570 .block_inline => {
564571 const pl_node = data[inst_index].pl_node;
565572 const extra = zir.extraData(Zir.Inst.Block, pl_node.payload_index);
......@@ -585,29 +592,41 @@ fn walkInstruction(
585592 if (tags[param_index] != .param) unreachable; // TODO: handle more param types
586593 const pl_tok = data[param_index].pl_tok;
587594 const extra = zir.extraData(Zir.Inst.Param, pl_tok.payload_index);
595 const doc_comment = if (extra.data.doc_comment != 0)
596 zir.nullTerminatedString(extra.data.doc_comment)
597 else
598 "";
588599
589600 param_ast_indexes.appendAssumeCapacity(self.ast_nodes.items.len);
590601 try self.ast_nodes.append(self.arena, .{
591 .name = zir.nullTerminatedString(zir.extra[extra.data.name]),
592 .docs = "",
602 .name = zir.nullTerminatedString(extra.data.name),
603 .docs = doc_comment,
593604 });
594605
595606 const break_index = zir.extra[extra.end..][extra.data.body_len - 1];
596607 const break_operand = data[break_index].@"break".operand;
597 const walk_res = try self.walkRef(zir, parent_scope, break_operand);
608 const param_type_ref = try self.walkRef(zir, parent_scope, break_operand);
598609
599610 param_type_refs.appendAssumeCapacity(
600 DocData.TypeRef.fromWalkResult(walk_res),
611 DocData.TypeRef.fromWalkResult(param_type_ref),
601612 );
602613 }
603614
615 // ret
616 const ret_type_ref = blk: {
617 const last_instr_index = fn_info.ret_ty_body[fn_info.ret_ty_body.len - 1];
618 const break_operand = data[last_instr_index].@"break".operand;
619 const wr = try self.walkRef(zir, parent_scope, break_operand);
620 break :blk DocData.TypeRef.fromWalkResult(wr);
621 };
622
604623 self.ast_nodes.items[self_ast_node_index].fields = param_ast_indexes.items;
605624 try self.types.append(self.arena, .{
606625 .Fn = .{
607626 .name = "todo_name func",
608627 .src = self_ast_node_index,
609628 .params = param_type_refs.items,
610 .ret = .{ .type = @enumToInt(Ref.void_type) },
629 .ret = ret_type_ref,
611630 },
612631 });
613632 return DocData.WalkResult{ .type = self.types.items.len - 1 };