authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2019-10-08 11:52:06-04:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2019-10-08 11:52:06-04:00
log6814d6b3321a8921ac714a4baf8952cc1864ed74
tree66c3155ec2b8dbc6686c77cdeab82fbc7ef5e044
parenta55db08a7b6326ea0d84f13acd9312d435c10136
signaturelock-open Commit is signed but in an unrecognized format.

generated docs: function parameters have links


3 files changed, 298 insertions(+), 10 deletions(-)

lib/std/special/docs/index.html+52
...@@ -145,6 +145,34 @@...@@ -145,6 +145,34 @@
145 #listSearchResults li.selected {145 #listSearchResults li.selected {
146 background-color: #93e196;146 background-color: #93e196;
147 }147 }
148 .tok-kw {
149 color: #333;
150 font-weight: bold;
151 }
152 .tok-str {
153 color: #d14;
154 }
155 .tok-builtin {
156 color: #0086b3;
157 }
158 .tok-comment {
159 color: #777;
160 font-style: italic;
161 }
162 .tok-fn {
163 color: #900;
164 font-weight: bold;
165 }
166 .tok-null {
167 color: #008080;
168 }
169 .tok-number {
170 color: #008080;
171 }
172 .tok-type {
173 color: #458;
174 font-weight: bold;
175 }
148176
149 @media (prefers-color-scheme: dark) {177 @media (prefers-color-scheme: dark) {
150 body{178 body{
...@@ -183,6 +211,30 @@...@@ -183,6 +211,30 @@
183 #listSearchResults li.selected a {211 #listSearchResults li.selected a {
184 color: #fff;212 color: #fff;
185 }213 }
214 .tok-kw {
215 color: #eee;
216 }
217 .tok-str {
218 color: #2e5;
219 }
220 .tok-builtin {
221 color: #ff894c;
222 }
223 .tok-comment {
224 color: #aa7;
225 }
226 .tok-fn {
227 color: #e33;
228 }
229 .tok-null {
230 color: #ff8080;
231 }
232 .tok-number {
233 color: #ff8080;
234 }
235 .tok-type {
236 color: #68f;
237 }
186 }238 }
187 </style>239 </style>
188 </head>240 </head>
lib/std/special/docs/main.js+160-5
...@@ -29,11 +29,17 @@...@@ -29,11 +29,17 @@
2929
30 var typeKindTypeId;30 var typeKindTypeId;
31 var typeKindFnId;31 var typeKindFnId;
32 var typeKindPtrId;
33 var typeKindFloatId;
34 var typeKindIntId;
32 findTypeKinds();35 findTypeKinds();
3336
34 // for each package, is an array with packages to get to this one37 // for each package, is an array with packages to get to this one
35 var canonPkgPaths = computeCanonicalPackagePaths();38 var canonPkgPaths = computeCanonicalPackagePaths();
39 // for each decl, is an array with {declNames, pkgNames} to get to this one
36 var canonDeclPaths = null; // lazy; use getCanonDeclPath40 var canonDeclPaths = null; // lazy; use getCanonDeclPath
41 // for each type, is an array with {declNames, pkgNames} to get to this one
42 var canonTypeDecls = null; // lazy; use getCanonTypeDecl
3743
38 var curNav = {44 var curNav = {
39 // each element is a package name, e.g. @import("a") then within there @import("b")45 // each element is a package name, e.g. @import("a") then within there @import("b")
...@@ -158,7 +164,29 @@...@@ -158,7 +164,29 @@
158164
159 function renderFn(fnDecl) {165 function renderFn(fnDecl) {
160 var typeObj = zigAnalysis.types[fnDecl.type];166 var typeObj = zigAnalysis.types[fnDecl.type];
161 domFnProtoCode.textContent = "fn " + fnDecl.name + typeObj.name.substring(2);167 var protoHtml = '<span class="tok-kw">fn</span> <span class="tok-fn">'
168 + escapeHtml(fnDecl.name) + '</span>(';
169 if (typeObj.args != null) {
170 for (var i = 0; i < typeObj.args.length; i += 1) {
171 if (i != 0) {
172 protoHtml += ', ';
173 }
174 var argTypeIndex = typeObj.args[i];
175 if (argTypeIndex != null) {
176 protoHtml += typeIndexName(argTypeIndex, true, true);
177 } else {
178 protoHtml += '<span class="tok-kw">var</span>';
179 }
180 }
181 }
182
183 protoHtml += ') ';
184 if (typeObj.ret != null) {
185 protoHtml += typeIndexName(typeObj.ret, true, true);
186 } else {
187 protoHtml += '<span class="tok-kw">var</span>';
188 }
189 domFnProtoCode.innerHTML = protoHtml;
162190
163 var docsSource = null;191 var docsSource = null;
164 var srcNode = zigAnalysis.astNodes[fnDecl.src];192 var srcNode = zigAnalysis.astNodes[fnDecl.src];
...@@ -306,9 +334,107 @@...@@ -306,9 +334,107 @@
306 }334 }
307 }335 }
308336
337 function typeIndexName(typeIndex, wantHtml, wantLink) {
338 var typeObj = zigAnalysis.types[typeIndex];
339 if (wantLink) {
340 var declIndex = getCanonTypeDecl(typeIndex);
341 var declPath = getCanonDeclPath(declIndex);
342 var haveLink = declPath != null;
343 var typeNameHtml = typeName(typeObj, true, !haveLink);
344 if (haveLink) {
345 return '<a href="' + navLink(declPath.pkgNames, declPath.declNames) + '">' + typeNameHtml + '</a>';
346 } else {
347 return typeNameHtml;
348 }
349 } else {
350 return typeName(typeObj, wantHtml);
351 }
352 }
353
354 function typeName(typeObj, wantHtml, wantSubLink) {
355 switch (typeObj.kind) {
356 case typeKindPtrId:
357 var name = "";
358 switch (typeObj.len) {
359 case 0:
360 default:
361 name += "*";
362 break;
363 case 1:
364 name += "[*]";
365 break;
366 case 2:
367 name += "[]";
368 break;
369 case 3:
370 name += "[*c]";
371 break;
372 }
373 if (typeObj['const']) {
374 if (wantHtml) {
375 name += '<span class="tok-kw">const</span> ';
376 } else {
377 name += "const ";
378 }
379 }
380 if (typeObj['volatile']) {
381 if (wantHtml) {
382 name += '<span class="tok-kw">volatile</span> ';
383 } else {
384 name += "volatile ";
385 }
386 }
387 if (typeObj.align != null) {
388 if (wantHtml) {
389 name += '<span class="tok-kw">align</span>(';
390 } else {
391 name += "align(";
392 }
393 if (wantHtml) {
394 name += '<span class="tok-number">' + typeObj.align + '</span>';
395 } else {
396 name += typeObj.align;
397 }
398 if (typeObj.hostIntBytes != null) {
399 name += ":" + typeObj.bitOffsetInHost + ":" + typeObj.hostIntBytes;
400 }
401 name += ") ";
402 }
403 name += typeIndexName(typeObj.elem, wantHtml, wantSubLink);
404 return name;
405 case typeKindFloatId:
406 if (wantHtml) {
407 return '<span class="tok-type">f' + typeObj.bits + '</span>';
408 } else {
409 return "f" + typeObj.bits;
410 }
411 case typeKindIntId:
412 var signed = (typeObj.i != null) ? 'i' : 'u';
413 var bits = typeObj[signed];
414 if (wantHtml) {
415 return '<span class="tok-type">' + signed + bits + '</span>';
416 } else {
417 return signed + bits;
418 }
419 case typeKindTypeId:
420 if (wantHtml) {
421 return '<span class="tok-type">type</span>';
422 } else {
423 return "type";
424 }
425 default:
426 if (wantHtml) {
427 return escapeHtml(typeObj.name);
428 } else {
429 return typeObj.name;
430 }
431 }
432 }
433
309 function renderType(typeObj) {434 function renderType(typeObj) {
310 if (typeObj.name != null && typeObj.name != "") {435 var name = typeName(typeObj);
311 domHdrName.innerText = zigAnalysis.typeKinds[typeObj.kind] + " " + typeObj.name;436 if (name != null && name != "") {
437 domHdrName.innerText = zigAnalysis.typeKinds[typeObj.kind] + " " + name;
312 domHdrName.classList.remove("hidden");438 domHdrName.classList.remove("hidden");
313 }439 }
314 }440 }
...@@ -402,6 +528,12 @@...@@ -402,6 +528,12 @@
402 typeKindTypeId = i;528 typeKindTypeId = i;
403 } else if (zigAnalysis.typeKinds[i] === "Fn") {529 } else if (zigAnalysis.typeKinds[i] === "Fn") {
404 typeKindFnId = i;530 typeKindFnId = i;
531 } else if (zigAnalysis.typeKinds[i] === "Pointer") {
532 typeKindPtrId = i;
533 } else if (zigAnalysis.typeKinds[i] === "Float") {
534 typeKindFloatId = i;
535 } else if (zigAnalysis.typeKinds[i] === "Int") {
536 typeKindIntId = i;
405 }537 }
406 }538 }
407 if (typeKindTypeId == null) {539 if (typeKindTypeId == null) {
...@@ -410,6 +542,15 @@...@@ -410,6 +542,15 @@
410 if (typeKindFnId == null) {542 if (typeKindFnId == null) {
411 throw new Error("No type kind 'Fn' found");543 throw new Error("No type kind 'Fn' found");
412 }544 }
545 if (typeKindPtrId == null) {
546 throw new Error("No type kind 'Pointer' found");
547 }
548 if (typeKindFloatId == null) {
549 throw new Error("No type kind 'Float' found");
550 }
551 if (typeKindIntId == null) {
552 throw new Error("No type kind 'Int' found");
553 }
413 }554 }
414555
415 function findTypeTypeId() {556 function findTypeTypeId() {
...@@ -500,6 +641,7 @@...@@ -500,6 +641,7 @@
500641
501 function computeCanonDeclPaths() {642 function computeCanonDeclPaths() {
502 var list = new Array(zigAnalysis.decls.length);643 var list = new Array(zigAnalysis.decls.length);
644 canonTypeDecls = new Array(zigAnalysis.types.length);
503645
504 for (var pkgI = 0; pkgI < zigAnalysis.packages.length; pkgI += 1) {646 for (var pkgI = 0; pkgI < zigAnalysis.packages.length; pkgI += 1) {
505 if (pkgI === zigAnalysis.rootPkg && rootIsStd) continue;647 if (pkgI === zigAnalysis.rootPkg && rootIsStd) continue;
...@@ -518,6 +660,9 @@...@@ -518,6 +660,9 @@
518 if (list[mainDeclIndex] != null) continue;660 if (list[mainDeclIndex] != null) continue;
519661
520 var decl = zigAnalysis.decls[mainDeclIndex];662 var decl = zigAnalysis.decls[mainDeclIndex];
663 if (decl.type === typeTypeId) {
664 canonTypeDecls[decl.value] = mainDeclIndex;
665 }
521 var declNames = item.declNames.concat([decl.name]);666 var declNames = item.declNames.concat([decl.name]);
522 list[mainDeclIndex] = {667 list[mainDeclIndex] = {
523 pkgNames: pkgNames,668 pkgNames: pkgNames,
...@@ -544,12 +689,22 @@...@@ -544,12 +689,22 @@
544 return canonDeclPaths[index];689 return canonDeclPaths[index];
545 }690 }
546691
547 function markdown(mdText) {692 function getCanonTypeDecl(index) {
548 return mdText.replace(/[&"<>]/g, function (m) {693 getCanonDeclPath(0);
694 return canonTypeDecls[index];
695 }
696
697 function escapeHtml(text) {
698 return text.replace(/[&"<>]/g, function (m) {
549 return escapeHtmlReplacements[m];699 return escapeHtmlReplacements[m];
550 });700 });
551 }701 }
552702
703 function markdown(mdText) {
704 // TODO implement more
705 return escapeHtml(mdText);
706 }
707
553 function onSearchKeyDown(ev) {708 function onSearchKeyDown(ev) {
554 switch (ev.which) {709 switch (ev.which) {
555 case 13:710 case 13:
src/dump_analysis.cpp+86-5
...@@ -683,24 +683,57 @@ static void anal_dump_value(AnalDumpCtx *ctx, AstNode *source_node, ZigType *ty,...@@ -683,24 +683,57 @@ static void anal_dump_value(AnalDumpCtx *ctx, AstNode *source_node, ZigType *ty,
683 zig_unreachable();683 zig_unreachable();
684}684}
685685
686static void anal_dump_pointer_attrs(AnalDumpCtx *ctx, ZigType *ty) {
687 JsonWriter *jw = &ctx->jw;
688 if (ty->data.pointer.explicit_alignment != 0) {
689 jw_object_field(jw, "align");
690 jw_int(jw, ty->data.pointer.explicit_alignment);
691 }
692 if (ty->data.pointer.is_const) {
693 jw_object_field(jw, "const");
694 jw_bool(jw, true);
695 }
696 if (ty->data.pointer.is_volatile) {
697 jw_object_field(jw, "volatile");
698 jw_bool(jw, true);
699 }
700 if (ty->data.pointer.allow_zero) {
701 jw_object_field(jw, "allowZero");
702 jw_bool(jw, true);
703 }
704 if (ty->data.pointer.host_int_bytes != 0) {
705 jw_object_field(jw, "hostIntBytes");
706 jw_int(jw, ty->data.pointer.host_int_bytes);
707
708 jw_object_field(jw, "bitOffsetInHost");
709 jw_int(jw, ty->data.pointer.bit_offset_in_host);
710 }
711
712 jw_object_field(jw, "elem");
713 anal_dump_type_ref(ctx, ty->data.pointer.child_type);
714}
715
686static void anal_dump_type(AnalDumpCtx *ctx, ZigType *ty) {716static void anal_dump_type(AnalDumpCtx *ctx, ZigType *ty) {
687 JsonWriter *jw = &ctx->jw;717 JsonWriter *jw = &ctx->jw;
688 jw_array_elem(jw);718 jw_array_elem(jw);
689 jw_begin_object(jw);719 jw_begin_object(jw);
690720
691 jw_object_field(jw, "name");
692 jw_string(jw, buf_ptr(&ty->name));
693
694 jw_object_field(jw, "kind");721 jw_object_field(jw, "kind");
695 jw_int(jw, type_id_index(ty));722 jw_int(jw, type_id_index(ty));
696723
697 switch (ty->id) {724 switch (ty->id) {
725 case ZigTypeIdMetaType:
726 break;
698 case ZigTypeIdStruct: {727 case ZigTypeIdStruct: {
699 if (ty->data.structure.is_slice) {728 if (ty->data.structure.is_slice) {
700 // TODO729 jw_object_field(jw, "len");
730 jw_int(jw, 2);
731 anal_dump_pointer_attrs(ctx, ty->data.structure.fields[slice_ptr_index].type_entry);
701 break;732 break;
702 }733 }
703734
735 jw_object_field(jw, "name");
736 jw_string(jw, buf_ptr(&ty->name));
704 {737 {
705 jw_object_field(jw, "pubDecls");738 jw_object_field(jw, "pubDecls");
706 jw_begin_array(jw);739 jw_begin_array(jw);
...@@ -755,13 +788,61 @@ static void anal_dump_type(AnalDumpCtx *ctx, ZigType *ty) {...@@ -755,13 +788,61 @@ static void anal_dump_type(AnalDumpCtx *ctx, ZigType *ty) {
755 jw_int(jw, ty->data.floating.bit_count);788 jw_int(jw, ty->data.floating.bit_count);
756 break;789 break;
757 }790 }
791 case ZigTypeIdInt: {
792 if (ty->data.integral.is_signed) {
793 jw_object_field(jw, "i");
794 } else {
795 jw_object_field(jw, "u");
796 }
797 jw_int(jw, ty->data.integral.bit_count);
798 break;
799 }
758 case ZigTypeIdFn: {800 case ZigTypeIdFn: {
801 jw_object_field(jw, "name");
802 jw_string(jw, buf_ptr(&ty->name));
803
759 jw_object_field(jw, "generic");804 jw_object_field(jw, "generic");
760 jw_bool(jw, ty->data.fn.is_generic);805 jw_bool(jw, ty->data.fn.is_generic);
806
807 if (ty->data.fn.fn_type_id.return_type != nullptr) {
808 jw_object_field(jw, "ret");
809 anal_dump_type_ref(ctx, ty->data.fn.fn_type_id.return_type);
810 }
811
812 if (ty->data.fn.fn_type_id.param_count != 0) {
813 jw_object_field(jw, "args");
814 jw_begin_array(jw);
815 for (size_t i = 0; i < ty->data.fn.fn_type_id.param_count; i += 1) {
816 jw_array_elem(jw);
817 if (ty->data.fn.fn_type_id.param_info[i].type != nullptr) {
818 anal_dump_type_ref(ctx, ty->data.fn.fn_type_id.param_info[i].type);
819 } else {
820 jw_null(jw);
821 }
822 }
823 jw_end_array(jw);
824 }
825 break;
826 }
827 case ZigTypeIdPointer: {
828 switch (ty->data.pointer.ptr_len) {
829 case PtrLenSingle:
830 break;
831 case PtrLenUnknown:
832 jw_object_field(jw, "len");
833 jw_int(jw, 1);
834 break;
835 case PtrLenC:
836 jw_object_field(jw, "len");
837 jw_int(jw, 3);
838 break;
839 }
840 anal_dump_pointer_attrs(ctx, ty);
761 break;841 break;
762 }842 }
763 default:843 default:
764 // TODO844 jw_object_field(jw, "name");
845 jw_string(jw, buf_ptr(&ty->name));
765 break;846 break;
766 }847 }
767 jw_end_object(jw);848 jw_end_object(jw);