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 @@...@@ -130,17 +130,17 @@
130 return typeKind === typeKinds.ErrorSet || typeKindIsContainer(typeKind);130 return typeKind === typeKinds.ErrorSet || typeKindIsContainer(typeKind);
131 }131 }
132132
133 function resolveDeclValue(decl) {133 function resolveValue(value) {
134 var i = 0;134 var i = 0;
135 while(i < 1000) {135 while(i < 1000) {
136 i += 1;136 i += 1;
137137
138 if ("declRef" in decl.value) {138 if ("declRef" in value) {
139 decl = zigAnalysis.decls[decl.value.declRef];139 value = zigAnalysis.decls[value.declRef].value;
140 continue;140 continue;
141 }141 }
142142
143 return decl.value;143 return value;
144144
145 }145 }
146 console.assert(false);146 console.assert(false);
...@@ -249,8 +249,9 @@...@@ -249,8 +249,9 @@
249 return render404();249 return render404();
250 }250 }
251251
252 var childDeclValue = resolveDeclValue(childDecl);252 var childDeclValue = resolveValue(childDecl.value);
253 if ("type" in childDeclValue){253 if ("type" in childDeclValue &&
254 zigAnalysis.types[childDeclValue.type].kind !== typeKinds.Fn){
254 if (i + 1 === curNav.declNames.length) {255 if (i + 1 === curNav.declNames.length) {
255 curNav.declObjs.push(zigAnalysis.types[childDeclValue.type]);256 curNav.declObjs.push(zigAnalysis.types[childDeclValue.type]);
256 break;257 break;
...@@ -277,7 +278,7 @@...@@ -277,7 +278,7 @@
277 } else if (lastIsDecl && last.kind === 'var') {278 } else if (lastIsDecl && last.kind === 'var') {
278 return renderVar(last);279 return renderVar(last);
279 } else if (lastIsDecl && last.kind === 'const' && !(declContainsType(last))) {280 } else if (lastIsDecl && last.kind === 'const' && !(declContainsType(last))) {
280 var typeObj = zigAnalysis.types[resolveDeclValueTypeId(last)];281 var typeObj = zigAnalysis.types[resolveValue(last.value).type];
281 if (typeObj.kind === typeKinds.Fn) {282 if (typeObj.kind === typeKinds.Fn) {
282 return renderFn(last);283 return renderFn(last);
283 } else {284 } else {
...@@ -321,7 +322,11 @@...@@ -321,7 +322,11 @@
321 }322 }
322323
323 function renderFn(fnDecl) {324 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
326 var docsSource = null;331 var docsSource = null;
327 var srcNode = zigAnalysis.astNodes[fnDecl.src];332 var srcNode = zigAnalysis.astNodes[fnDecl.src];
...@@ -329,26 +334,23 @@...@@ -329,26 +334,23 @@
329 docsSource = srcNode.docs;334 docsSource = srcNode.docs;
330 }335 }
331336
332 var typeObj = zigAnalysis.types[fnDecl.type];337 var retIndex = resolveValue(typeObj.ret).type;
333 renderFnParamDocs(fnDecl, typeObj);338 renderFnParamDocs(fnDecl, typeObj);
334339
335 var errSetTypeIndex = null;340 var errSetTypeIndex = null;
336 if (typeObj.ret != null) {341 var retType = zigAnalysis.types[retIndex];
337 var retType = zigAnalysis.types[typeObj.ret];342 if (retType.kind === typeKinds.ErrorSet) {
338 if (retType.kind === typeKinds.ErrorSet) {343 errSetTypeIndex = retIndex;
339 errSetTypeIndex = typeObj.ret;344 } else if (retType.kind === typeKinds.ErrorUnion) {
340 } else if (retType.kind === typeKinds.ErrorUnion) {345 errSetTypeIndex = retType.err;
341 errSetTypeIndex = retType.err;
342 }
343 }346 }
344 if (errSetTypeIndex != null) {347 if (errSetTypeIndex != null) {
345 var errSetType = zigAnalysis.types[errSetTypeIndex];348 var errSetType = zigAnalysis.types[errSetTypeIndex];
346 renderErrorSet(errSetType);349 renderErrorSet(errSetType);
347 }350 }
348351
349 var fnObj = zigAnalysis.fns[fnDecl.value];352 var protoSrcIndex = fnDecl.src;
350 var protoSrcIndex = fnObj.src;353 if (typeIsGenericFn(value.type)) {
351 if (typeIsGenericFn(fnDecl.type)) {
352 var instantiations = nodesToFnsMap[protoSrcIndex];354 var instantiations = nodesToFnsMap[protoSrcIndex];
353 var calls = nodesToCallsMap[protoSrcIndex];355 var calls = nodesToCallsMap[protoSrcIndex];
354 if (instantiations == null && calls == null) {356 if (instantiations == null && calls == null) {
...@@ -388,8 +390,7 @@...@@ -388,8 +390,7 @@
388 function renderFnParamDocs(fnDecl, typeObj) {390 function renderFnParamDocs(fnDecl, typeObj) {
389 var docCount = 0;391 var docCount = 0;
390392
391 var fnObj = zigAnalysis.fns[fnDecl.value];393 var fnNode = zigAnalysis.astNodes[fnDecl.src];
392 var fnNode = zigAnalysis.astNodes[fnObj.src];
393 var fields = fnNode.fields;394 var fields = fnNode.fields;
394 var isVarArgs = fnNode.varArgs;395 var isVarArgs = fnNode.varArgs;
395396
...@@ -415,10 +416,11 @@...@@ -415,10 +416,11 @@
415 }416 }
416 var divDom = domListParams.children[domIndex];417 var divDom = domListParams.children[domIndex];
417 domIndex += 1;418 domIndex += 1;
418 var argTypeIndex = typeObj.args[i];419 var value = resolveValue(typeObj.params[i]);
419420 console.assert("type" in value);
421 var argTypeIndex = value.type;
420 var html = '<pre>' + escapeHtml(fieldNode.name) + ": ";422 var html = '<pre>' + escapeHtml(fieldNode.name) + ": ";
421 if (isVarArgs && i === typeObj.args.length - 1) {423 if (isVarArgs && i === typeObj.params.length - 1) {
422 html += '...';424 html += '...';
423 } else if (argTypeIndex != null) {425 } else if (argTypeIndex != null) {
424 html += typeIndexName(argTypeIndex, true, true);426 html += typeIndexName(argTypeIndex, true, true);
...@@ -741,11 +743,7 @@...@@ -741,11 +743,7 @@
741 return "f" + typeObj.bits;743 return "f" + typeObj.bits;
742 }744 }
743 case typeKinds.Int:745 case typeKinds.Int:
744 var signed = (typeObj.i != null) ? 'i' : 'u';746 var name = typeObj.name;
745 var bits = typeObj[signed] || typeObj.name;
746
747 var name = typeObj.name ? typeObj.name : signed + bits;
748
749 if (wantHtml) {747 if (wantHtml) {
750 return '<span class="tok-type">' + name + '</span>';748 return '<span class="tok-type">' + name + '</span>';
751 } else {749 } else {
...@@ -834,22 +832,21 @@...@@ -834,22 +832,21 @@
834 payloadHtml += 'fn'832 payloadHtml += 'fn'
835 }833 }
836 payloadHtml += '(';834 payloadHtml += '(';
837 if (typeObj.args != null) {835 if (typeObj.params) {
838 var fields = null;836 var fields = null;
839 var isVarArgs = false;837 var isVarArgs = false;
840 if (fnDecl != null) {838 var fnNode = zigAnalysis.astNodes[fnDecl.src];
841 var fnObj = zigAnalysis.fns[fnDecl.value];839 fields = fnNode.fields;
842 var fnNode = zigAnalysis.astNodes[fnObj.src];840 isVarArgs = fnNode.varArgs;
843 fields = fnNode.fields;
844 isVarArgs = fnNode.varArgs;
845 }
846841
847 for (var i = 0; i < typeObj.args.length; i += 1) {842 for (var i = 0; i < typeObj.params.length; i += 1) {
848 if (i != 0) {843 if (i != 0) {
849 payloadHtml += ', ';844 payloadHtml += ', ';
850 }845 }
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
854 if (fields != null) {851 if (fields != null) {
855 var paramNode = zigAnalysis.astNodes[fields[i]];852 var paramNode = zigAnalysis.astNodes[fields[i]];
...@@ -896,13 +893,17 @@...@@ -896,13 +893,17 @@
896 }893 }
897 }894 }
898895
896 var retValue = resolveValue(typeObj.ret);
897 console.assert("type" in retValue);
898 var retTypeIndex = retValue.type;
899
899 payloadHtml += ') ';900 payloadHtml += ') ';
900 if (typeObj.ret != null) {901 if (retTypeIndex != null) {
901 payloadHtml += typeIndexName(typeObj.ret, wantHtml, wantSubLink, fnDecl);902 payloadHtml += typeIndexName(retTypeIndex, wantHtml, wantSubLink, fnDecl);
902 } else if (wantHtml) {903 } else if (wantHtml) {
903 payloadHtml += '<span class="tok-kw">var</span>';904 payloadHtml += '<span class="tok-kw">anytype</span>';
904 } else {905 } else {
905 payloadHtml += 'var';906 payloadHtml += 'anytype';
906 }907 }
907 return payloadHtml;908 return payloadHtml;
908 default:909 default:
...@@ -1233,7 +1234,7 @@...@@ -1233,7 +1234,7 @@
1233 html += '<span class="tok-kw" style="color:red;">#FAILURE#</span>';1234 html += '<span class="tok-kw" style="color:red;">#FAILURE#</span>';
1234 } else if ("declRef" in field) {1235 } else if ("declRef" in field) {
1235 var decl = zigAnalysis.decls[field.declRef];1236 var decl = zigAnalysis.decls[field.declRef];
1236 var val = resolveDeclValue(decl);1237 var val = resolveValue(decl.value);
1237 console.assert("type" in val);1238 console.assert("type" in val);
1238 var valType = zigAnalysis.types[val.type];1239 var valType = zigAnalysis.types[val.type];
12391240
src/Autodoc.zig+24-5
...@@ -560,6 +560,13 @@ fn walkInstruction(...@@ -560,6 +560,13 @@ fn walkInstruction(
560 });560 });
561 return DocData.WalkResult{ .type = self.types.items.len - 1 };561 return DocData.WalkResult{ .type = self.types.items.len - 1 };
562 },562 },
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 //},
563 .block_inline => {570 .block_inline => {
564 const pl_node = data[inst_index].pl_node;571 const pl_node = data[inst_index].pl_node;
565 const extra = zir.extraData(Zir.Inst.Block, pl_node.payload_index);572 const extra = zir.extraData(Zir.Inst.Block, pl_node.payload_index);
...@@ -585,29 +592,41 @@ fn walkInstruction(...@@ -585,29 +592,41 @@ fn walkInstruction(
585 if (tags[param_index] != .param) unreachable; // TODO: handle more param types592 if (tags[param_index] != .param) unreachable; // TODO: handle more param types
586 const pl_tok = data[param_index].pl_tok;593 const pl_tok = data[param_index].pl_tok;
587 const extra = zir.extraData(Zir.Inst.Param, pl_tok.payload_index);594 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
589 param_ast_indexes.appendAssumeCapacity(self.ast_nodes.items.len);600 param_ast_indexes.appendAssumeCapacity(self.ast_nodes.items.len);
590 try self.ast_nodes.append(self.arena, .{601 try self.ast_nodes.append(self.arena, .{
591 .name = zir.nullTerminatedString(zir.extra[extra.data.name]),602 .name = zir.nullTerminatedString(extra.data.name),
592 .docs = "",603 .docs = doc_comment,
593 });604 });
594605
595 const break_index = zir.extra[extra.end..][extra.data.body_len - 1];606 const break_index = zir.extra[extra.end..][extra.data.body_len - 1];
596 const break_operand = data[break_index].@"break".operand;607 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
599 param_type_refs.appendAssumeCapacity(610 param_type_refs.appendAssumeCapacity(
600 DocData.TypeRef.fromWalkResult(walk_res),611 DocData.TypeRef.fromWalkResult(param_type_ref),
601 );612 );
602 }613 }
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
604 self.ast_nodes.items[self_ast_node_index].fields = param_ast_indexes.items;623 self.ast_nodes.items[self_ast_node_index].fields = param_ast_indexes.items;
605 try self.types.append(self.arena, .{624 try self.types.append(self.arena, .{
606 .Fn = .{625 .Fn = .{
607 .name = "todo_name func",626 .name = "todo_name func",
608 .src = self_ast_node_index,627 .src = self_ast_node_index,
609 .params = param_type_refs.items,628 .params = param_type_refs.items,
610 .ret = .{ .type = @enumToInt(Ref.void_type) },629 .ret = ret_type_ref,
611 },630 },
612 });631 });
613 return DocData.WalkResult{ .type = self.types.items.len - 1 };632 return DocData.WalkResult{ .type = self.types.items.len - 1 };