authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2019-10-07 12:20:59-04:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2019-10-07 12:21:11-04:00
log2ccb48ddc3f3b543bca0538da948013447afe429
treed5230955957aea82230a0274af8d1f5c987b032f
parent85b8854c417a3b4bf2347c4f3709a047c4d311bd
signaturelock-open Commit is signed but in an unrecognized format.

generated docs: show doc comments on functions

7 files changed, 115 insertions(+), 11 deletions(-)

lib/std/special/docs/index.html+2
......@@ -7,6 +7,7 @@
77 <style type="text/css">
88 body {
99 font-family: system-ui, -apple-system, Roboto, "Segoe UI", sans-serif;
10 max-width: 60em;
1011 }
1112 .hidden {
1213 display: none;
......@@ -64,6 +65,7 @@
6465 <div id="fnProto" class="hidden">
6566 <pre id="fnProtoCode"></pre>
6667 </div>
68 <div id="fnDocs" class="hidden"></div>
6769 <div id="sectPkgs" class="hidden">
6870 <h2>Packages</h2>
6971 <ul id="listPkgs">
lib/std/special/docs/main.js+19-4
......@@ -10,6 +10,7 @@
1010 var domListFns = document.getElementById("listFns");
1111 var domFnProto = document.getElementById("fnProto");
1212 var domFnProtoCode = document.getElementById("fnProtoCode");
13 var domFnDocs = document.getElementById("fnDocs");
1314
1415 var typeKindTypeId;
1516 var typeKindFnId;
......@@ -53,6 +54,11 @@
5354 function render() {
5455 domStatus.classList.add("hidden");
5556 domFnProto.classList.add("hidden");
57 domFnDocs.classList.add("hidden");
58 domSectPkgs.classList.add("hidden");
59 domSectTypes.classList.add("hidden");
60 domSectFns.classList.add("hidden");
61
5662
5763 renderTitle();
5864
......@@ -107,13 +113,15 @@
107113 }
108114
109115 function renderFn(fnDecl) {
110 domSectPkgs.classList.add("hidden");
111 domSectTypes.classList.add("hidden");
112 domSectFns.classList.add("hidden");
113
114116 var typeObj = zigAnalysis.types[fnDecl.type];
115117 domFnProtoCode.textContent = "fn " + fnDecl.name + typeObj.name.substring(2);
116118
119 var srcNode = zigAnalysis.astNodes[fnDecl.src];
120 if (srcNode.docs != null) {
121 domFnDocs.innerHTML = markdown(srcNode.docs);
122 domFnDocs.classList.remove("hidden");
123 }
124
117125 domFnProto.classList.remove("hidden");
118126 }
119127
......@@ -379,4 +387,11 @@
379387 }
380388 return list;
381389 }
390
391 var escapeHtmlReplacements = { "&": "&amp;", '"': "&quot;", "<": "&lt;", ">": "&gt;" };
392 function markdown(mdText) {
393 return mdText.replace(/[&"<>]/g, function (m) {
394 return escapeHtmlReplacements[m];
395 });
396 }
382397})();
src/all_types.hpp+3
......@@ -1322,6 +1322,9 @@ bool pkg_ptr_eql(const ZigPackage *a, const ZigPackage *b);
13221322uint32_t tld_ptr_hash(const Tld *ptr);
13231323bool tld_ptr_eql(const Tld *a, const Tld *b);
13241324
1325uint32_t node_ptr_hash(const AstNode *ptr);
1326bool node_ptr_eql(const AstNode *a, const AstNode *b);
1327
13251328struct ZigTypeUnion {
13261329 AstNode *decl_node;
13271330 TypeUnionField *fields;
src/analyze.cpp+8
......@@ -7320,6 +7320,14 @@ bool tld_ptr_eql(const Tld *a, const Tld *b) {
73207320 return a == b;
73217321}
73227322
7323uint32_t node_ptr_hash(const AstNode *ptr) {
7324 return hash_ptr((void*)ptr);
7325}
7326
7327bool node_ptr_eql(const AstNode *a, const AstNode *b) {
7328 return a == b;
7329}
7330
73237331ConstExprValue *get_builtin_value(CodeGen *codegen, const char *name) {
73247332 Tld *tld = get_container_scope(codegen->compile_var_import)->decl_table.get(buf_create_from_str(name));
73257333 resolve_top_level_decl(codegen, tld, nullptr, false);
src/buffer.hpp+6
......@@ -38,6 +38,12 @@ static inline char *buf_ptr(Buf *buf) {
3838 return buf->list.items;
3939}
4040
41static inline const char *buf_ptr(const Buf *buf) {
42 assert(buf);
43 assert(buf->list.length);
44 return buf->list.items;
45}
46
4147static inline void buf_resize(Buf *buf, size_t new_len) {
4248 buf->list.resize(new_len + 1);
4349 buf->list.at(buf_len(buf)) = 0;
src/dump_analysis.cpp+75-5
......@@ -351,6 +351,9 @@ struct AnalDumpCtx {
351351
352352 ZigList<Tld *> decl_list;
353353 HashMap<const Tld *, uint32_t, tld_ptr_hash, tld_ptr_eql> decl_map;
354
355 ZigList<AstNode *> node_list;
356 HashMap<const AstNode *, uint32_t, node_ptr_hash, node_ptr_eql> node_map;
354357};
355358
356359static uint32_t anal_dump_get_type_id(AnalDumpCtx *ctx, ZigType *ty);
......@@ -416,6 +419,17 @@ static uint32_t anal_dump_get_file_id(AnalDumpCtx *ctx, Buf *file) {
416419 return file_id;
417420}
418421
422static uint32_t anal_dump_get_node_id(AnalDumpCtx *ctx, AstNode *node) {
423 uint32_t node_id = ctx->node_list.length;
424 auto existing_entry = ctx->node_map.put_unique(node, node_id);
425 if (existing_entry == nullptr) {
426 ctx->node_list.append(node);
427 } else {
428 node_id = existing_entry->value;
429 }
430 return node_id;
431}
432
419433static uint32_t anal_dump_get_decl_id(AnalDumpCtx *ctx, Tld *tld) {
420434 uint32_t decl_id = ctx->decl_list.length;
421435 auto existing_entry = ctx->decl_map.put_unique(tld, decl_id);
......@@ -475,6 +489,11 @@ static void anal_dump_file_ref(AnalDumpCtx *ctx, Buf *file) {
475489 jw_int(&ctx->jw, file_id);
476490}
477491
492static void anal_dump_node_ref(AnalDumpCtx *ctx, AstNode *node) {
493 uint32_t node_id = anal_dump_get_node_id(ctx, node);
494 jw_int(&ctx->jw, node_id);
495}
496
478497static void anal_dump_decl_ref(AnalDumpCtx *ctx, Tld *tld) {
479498 uint32_t decl_id = anal_dump_get_decl_id(ctx, tld);
480499 jw_int(&ctx->jw, decl_id);
......@@ -536,11 +555,8 @@ static void anal_dump_decl(AnalDumpCtx *ctx, Tld *tld) {
536555 jw_object_field(jw, "import");
537556 anal_dump_type_ref(ctx, tld->import);
538557
539 jw_object_field(jw, "line");
540 jw_int(jw, tld->source_node->line);
541
542 jw_object_field(jw, "col");
543 jw_int(jw, tld->source_node->column);
558 jw_object_field(jw, "src");
559 anal_dump_node_ref(ctx, tld->source_node);
544560
545561 jw_object_field(jw, "name");
546562 jw_string(jw, buf_ptr(tld->name));
......@@ -712,6 +728,50 @@ static void anal_dump_type(AnalDumpCtx *ctx, ZigType *ty) {
712728 jw_end_object(jw);
713729}
714730
731void anal_dump_node(AnalDumpCtx *ctx, const AstNode *node) {
732 JsonWriter *jw = &ctx->jw;
733
734 jw_begin_object(jw);
735
736 jw_object_field(jw, "file");
737 anal_dump_file_ref(ctx, node->owner->data.structure.root_struct->path);
738
739 jw_object_field(jw, "line");
740 jw_int(jw, node->line);
741
742 jw_object_field(jw, "col");
743 jw_int(jw, node->column);
744
745 const Buf *doc_comments_buf;
746 switch (node->type) {
747 case NodeTypeParamDecl:
748 doc_comments_buf = &node->data.param_decl.doc_comments;
749 break;
750 case NodeTypeFnProto:
751 doc_comments_buf = &node->data.fn_proto.doc_comments;
752 break;
753 case NodeTypeVariableDeclaration:
754 doc_comments_buf = &node->data.variable_declaration.doc_comments;
755 break;
756 case NodeTypeErrorSetField:
757 doc_comments_buf = &node->data.err_set_field.doc_comments;
758 break;
759 case NodeTypeStructField:
760 doc_comments_buf = &node->data.struct_field.doc_comments;
761 break;
762 default:
763 doc_comments_buf = nullptr;
764 break;
765 }
766 if (doc_comments_buf->list.length != 0) {
767 jw_object_field(jw, "docs");
768 jw_string(jw, buf_ptr(doc_comments_buf));
769 }
770
771 jw_end_object(jw);
772}
773
774
715775void zig_print_analysis_dump(CodeGen *g, FILE *f, const char *one_indent, const char *nl) {
716776 Error err;
717777 AnalDumpCtx ctx = {};
......@@ -722,6 +782,7 @@ void zig_print_analysis_dump(CodeGen *g, FILE *f, const char *one_indent, const
722782 ctx.pkg_map.init(16);
723783 ctx.file_map.init(16);
724784 ctx.decl_map.init(16);
785 ctx.node_map.init(16);
725786
726787 jw_begin_object(jw);
727788
......@@ -794,5 +855,14 @@ void zig_print_analysis_dump(CodeGen *g, FILE *f, const char *one_indent, const
794855 }
795856 jw_end_array(jw);
796857
858 jw_object_field(jw, "astNodes");
859 jw_begin_array(jw);
860 for (uint32_t i = 0; i < ctx.node_list.length; i += 1) {
861 const AstNode *node = ctx.node_list.at(i);
862 jw_array_elem(jw);
863 anal_dump_node(&ctx, node);
864 }
865 jw_end_array(jw);
866
797867 jw_end_object(jw);
798868}
src/parser.cpp+2-2
......@@ -503,9 +503,9 @@ static Token *ast_parse_doc_comments(ParseContext *pc, Buf *buf) {
503503 if (buf->list.length == 0) {
504504 buf_resize(buf, 0);
505505 }
506 // chops off '///' and '\n'
506 // chops off '///' but leaves '\n'
507507 buf_append_mem(buf, buf_ptr(pc->buf) + doc_token->start_pos + 3,
508 doc_token->end_pos - doc_token->start_pos - 4);
508 doc_token->end_pos - doc_token->start_pos - 3);
509509 }
510510 return doc_token;
511511}