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 @@
145145 #listSearchResults li.selected {
146146 background-color: #93e196;
147147 }
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
149177 @media (prefers-color-scheme: dark) {
150178 body{
......@@ -183,6 +211,30 @@
183211 #listSearchResults li.selected a {
184212 color: #fff;
185213 }
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 }
186238 }
187239 </style>
188240 </head>
lib/std/special/docs/main.js+160-5
......@@ -29,11 +29,17 @@
2929
3030 var typeKindTypeId;
3131 var typeKindFnId;
32 var typeKindPtrId;
33 var typeKindFloatId;
34 var typeKindIntId;
3235 findTypeKinds();
3336
3437 // for each package, is an array with packages to get to this one
3538 var canonPkgPaths = computeCanonicalPackagePaths();
39 // for each decl, is an array with {declNames, pkgNames} to get to this one
3640 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
3844 var curNav = {
3945 // each element is a package name, e.g. @import("a") then within there @import("b")
......@@ -158,7 +164,29 @@
158164
159165 function renderFn(fnDecl) {
160166 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
163191 var docsSource = null;
164192 var srcNode = zigAnalysis.astNodes[fnDecl.src];
......@@ -306,9 +334,107 @@
306334 }
307335 }
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
309434 function renderType(typeObj) {
310 if (typeObj.name != null && typeObj.name != "") {
311 domHdrName.innerText = zigAnalysis.typeKinds[typeObj.kind] + " " + typeObj.name;
435 var name = typeName(typeObj);
436 if (name != null && name != "") {
437 domHdrName.innerText = zigAnalysis.typeKinds[typeObj.kind] + " " + name;
312438 domHdrName.classList.remove("hidden");
313439 }
314440 }
......@@ -402,6 +528,12 @@
402528 typeKindTypeId = i;
403529 } else if (zigAnalysis.typeKinds[i] === "Fn") {
404530 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;
405537 }
406538 }
407539 if (typeKindTypeId == null) {
......@@ -410,6 +542,15 @@
410542 if (typeKindFnId == null) {
411543 throw new Error("No type kind 'Fn' found");
412544 }
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 }
413554 }
414555
415556 function findTypeTypeId() {
......@@ -500,6 +641,7 @@
500641
501642 function computeCanonDeclPaths() {
502643 var list = new Array(zigAnalysis.decls.length);
644 canonTypeDecls = new Array(zigAnalysis.types.length);
503645
504646 for (var pkgI = 0; pkgI < zigAnalysis.packages.length; pkgI += 1) {
505647 if (pkgI === zigAnalysis.rootPkg && rootIsStd) continue;
......@@ -518,6 +660,9 @@
518660 if (list[mainDeclIndex] != null) continue;
519661
520662 var decl = zigAnalysis.decls[mainDeclIndex];
663 if (decl.type === typeTypeId) {
664 canonTypeDecls[decl.value] = mainDeclIndex;
665 }
521666 var declNames = item.declNames.concat([decl.name]);
522667 list[mainDeclIndex] = {
523668 pkgNames: pkgNames,
......@@ -544,12 +689,22 @@
544689 return canonDeclPaths[index];
545690 }
546691
547 function markdown(mdText) {
548 return mdText.replace(/[&"<>]/g, function (m) {
692 function getCanonTypeDecl(index) {
693 getCanonDeclPath(0);
694 return canonTypeDecls[index];
695 }
696
697 function escapeHtml(text) {
698 return text.replace(/[&"<>]/g, function (m) {
549699 return escapeHtmlReplacements[m];
550700 });
551701 }
552702
703 function markdown(mdText) {
704 // TODO implement more
705 return escapeHtml(mdText);
706 }
707
553708 function onSearchKeyDown(ev) {
554709 switch (ev.which) {
555710 case 13:
src/dump_analysis.cpp+86-5
......@@ -683,24 +683,57 @@ static void anal_dump_value(AnalDumpCtx *ctx, AstNode *source_node, ZigType *ty,
683683 zig_unreachable();
684684}
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
686716static void anal_dump_type(AnalDumpCtx *ctx, ZigType *ty) {
687717 JsonWriter *jw = &ctx->jw;
688718 jw_array_elem(jw);
689719 jw_begin_object(jw);
690720
691 jw_object_field(jw, "name");
692 jw_string(jw, buf_ptr(&ty->name));
693
694721 jw_object_field(jw, "kind");
695722 jw_int(jw, type_id_index(ty));
696723
697724 switch (ty->id) {
725 case ZigTypeIdMetaType:
726 break;
698727 case ZigTypeIdStruct: {
699728 if (ty->data.structure.is_slice) {
700 // TODO
729 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);
701732 break;
702733 }
703734
735 jw_object_field(jw, "name");
736 jw_string(jw, buf_ptr(&ty->name));
704737 {
705738 jw_object_field(jw, "pubDecls");
706739 jw_begin_array(jw);
......@@ -755,13 +788,61 @@ static void anal_dump_type(AnalDumpCtx *ctx, ZigType *ty) {
755788 jw_int(jw, ty->data.floating.bit_count);
756789 break;
757790 }
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 }
758800 case ZigTypeIdFn: {
801 jw_object_field(jw, "name");
802 jw_string(jw, buf_ptr(&ty->name));
803
759804 jw_object_field(jw, "generic");
760805 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);
761841 break;
762842 }
763843 default:
764 // TODO
844 jw_object_field(jw, "name");
845 jw_string(jw, buf_ptr(&ty->name));
765846 break;
766847 }
767848 jw_end_object(jw);