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 @@...@@ -7,6 +7,7 @@
7 <style type="text/css">7 <style type="text/css">
8 body {8 body {
9 font-family: system-ui, -apple-system, Roboto, "Segoe UI", sans-serif;9 font-family: system-ui, -apple-system, Roboto, "Segoe UI", sans-serif;
10 max-width: 60em;
10 }11 }
11 .hidden {12 .hidden {
12 display: none;13 display: none;
...@@ -64,6 +65,7 @@...@@ -64,6 +65,7 @@
64 <div id="fnProto" class="hidden">65 <div id="fnProto" class="hidden">
65 <pre id="fnProtoCode"></pre>66 <pre id="fnProtoCode"></pre>
66 </div>67 </div>
68 <div id="fnDocs" class="hidden"></div>
67 <div id="sectPkgs" class="hidden">69 <div id="sectPkgs" class="hidden">
68 <h2>Packages</h2>70 <h2>Packages</h2>
69 <ul id="listPkgs">71 <ul id="listPkgs">
lib/std/special/docs/main.js+19-4
...@@ -10,6 +10,7 @@...@@ -10,6 +10,7 @@
10 var domListFns = document.getElementById("listFns");10 var domListFns = document.getElementById("listFns");
11 var domFnProto = document.getElementById("fnProto");11 var domFnProto = document.getElementById("fnProto");
12 var domFnProtoCode = document.getElementById("fnProtoCode");12 var domFnProtoCode = document.getElementById("fnProtoCode");
13 var domFnDocs = document.getElementById("fnDocs");
1314
14 var typeKindTypeId;15 var typeKindTypeId;
15 var typeKindFnId;16 var typeKindFnId;
...@@ -53,6 +54,11 @@...@@ -53,6 +54,11 @@
53 function render() {54 function render() {
54 domStatus.classList.add("hidden");55 domStatus.classList.add("hidden");
55 domFnProto.classList.add("hidden");56 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
57 renderTitle();63 renderTitle();
5864
...@@ -107,13 +113,15 @@...@@ -107,13 +113,15 @@
107 }113 }
108114
109 function renderFn(fnDecl) {115 function renderFn(fnDecl) {
110 domSectPkgs.classList.add("hidden");
111 domSectTypes.classList.add("hidden");
112 domSectFns.classList.add("hidden");
113
114 var typeObj = zigAnalysis.types[fnDecl.type];116 var typeObj = zigAnalysis.types[fnDecl.type];
115 domFnProtoCode.textContent = "fn " + fnDecl.name + typeObj.name.substring(2);117 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
117 domFnProto.classList.remove("hidden");125 domFnProto.classList.remove("hidden");
118 }126 }
119127
...@@ -379,4 +387,11 @@...@@ -379,4 +387,11 @@
379 }387 }
380 return list;388 return list;
381 }389 }
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 }
382})();397})();
src/all_types.hpp+3
...@@ -1322,6 +1322,9 @@ bool pkg_ptr_eql(const ZigPackage *a, const ZigPackage *b);...@@ -1322,6 +1322,9 @@ bool pkg_ptr_eql(const ZigPackage *a, const ZigPackage *b);
1322uint32_t tld_ptr_hash(const Tld *ptr);1322uint32_t tld_ptr_hash(const Tld *ptr);
1323bool tld_ptr_eql(const Tld *a, const Tld *b);1323bool 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
1325struct ZigTypeUnion {1328struct ZigTypeUnion {
1326 AstNode *decl_node;1329 AstNode *decl_node;
1327 TypeUnionField *fields;1330 TypeUnionField *fields;
src/analyze.cpp+8
...@@ -7320,6 +7320,14 @@ bool tld_ptr_eql(const Tld *a, const Tld *b) {...@@ -7320,6 +7320,14 @@ bool tld_ptr_eql(const Tld *a, const Tld *b) {
7320 return a == b;7320 return a == b;
7321}7321}
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
7323ConstExprValue *get_builtin_value(CodeGen *codegen, const char *name) {7331ConstExprValue *get_builtin_value(CodeGen *codegen, const char *name) {
7324 Tld *tld = get_container_scope(codegen->compile_var_import)->decl_table.get(buf_create_from_str(name));7332 Tld *tld = get_container_scope(codegen->compile_var_import)->decl_table.get(buf_create_from_str(name));
7325 resolve_top_level_decl(codegen, tld, nullptr, false);7333 resolve_top_level_decl(codegen, tld, nullptr, false);
src/buffer.hpp+6
...@@ -38,6 +38,12 @@ static inline char *buf_ptr(Buf *buf) {...@@ -38,6 +38,12 @@ static inline char *buf_ptr(Buf *buf) {
38 return buf->list.items;38 return buf->list.items;
39}39}
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
41static inline void buf_resize(Buf *buf, size_t new_len) {47static inline void buf_resize(Buf *buf, size_t new_len) {
42 buf->list.resize(new_len + 1);48 buf->list.resize(new_len + 1);
43 buf->list.at(buf_len(buf)) = 0;49 buf->list.at(buf_len(buf)) = 0;
src/dump_analysis.cpp+75-5
...@@ -351,6 +351,9 @@ struct AnalDumpCtx {...@@ -351,6 +351,9 @@ struct AnalDumpCtx {
351351
352 ZigList<Tld *> decl_list;352 ZigList<Tld *> decl_list;
353 HashMap<const Tld *, uint32_t, tld_ptr_hash, tld_ptr_eql> decl_map;353 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;
354};357};
355358
356static uint32_t anal_dump_get_type_id(AnalDumpCtx *ctx, ZigType *ty);359static 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) {...@@ -416,6 +419,17 @@ static uint32_t anal_dump_get_file_id(AnalDumpCtx *ctx, Buf *file) {
416 return file_id;419 return file_id;
417}420}
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
419static uint32_t anal_dump_get_decl_id(AnalDumpCtx *ctx, Tld *tld) {433static uint32_t anal_dump_get_decl_id(AnalDumpCtx *ctx, Tld *tld) {
420 uint32_t decl_id = ctx->decl_list.length;434 uint32_t decl_id = ctx->decl_list.length;
421 auto existing_entry = ctx->decl_map.put_unique(tld, decl_id);435 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) {...@@ -475,6 +489,11 @@ static void anal_dump_file_ref(AnalDumpCtx *ctx, Buf *file) {
475 jw_int(&ctx->jw, file_id);489 jw_int(&ctx->jw, file_id);
476}490}
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
478static void anal_dump_decl_ref(AnalDumpCtx *ctx, Tld *tld) {497static void anal_dump_decl_ref(AnalDumpCtx *ctx, Tld *tld) {
479 uint32_t decl_id = anal_dump_get_decl_id(ctx, tld);498 uint32_t decl_id = anal_dump_get_decl_id(ctx, tld);
480 jw_int(&ctx->jw, decl_id);499 jw_int(&ctx->jw, decl_id);
...@@ -536,11 +555,8 @@ static void anal_dump_decl(AnalDumpCtx *ctx, Tld *tld) {...@@ -536,11 +555,8 @@ static void anal_dump_decl(AnalDumpCtx *ctx, Tld *tld) {
536 jw_object_field(jw, "import");555 jw_object_field(jw, "import");
537 anal_dump_type_ref(ctx, tld->import);556 anal_dump_type_ref(ctx, tld->import);
538557
539 jw_object_field(jw, "line");558 jw_object_field(jw, "src");
540 jw_int(jw, tld->source_node->line);559 anal_dump_node_ref(ctx, tld->source_node);
541
542 jw_object_field(jw, "col");
543 jw_int(jw, tld->source_node->column);
544560
545 jw_object_field(jw, "name");561 jw_object_field(jw, "name");
546 jw_string(jw, buf_ptr(tld->name));562 jw_string(jw, buf_ptr(tld->name));
...@@ -712,6 +728,50 @@ static void anal_dump_type(AnalDumpCtx *ctx, ZigType *ty) {...@@ -712,6 +728,50 @@ static void anal_dump_type(AnalDumpCtx *ctx, ZigType *ty) {
712 jw_end_object(jw);728 jw_end_object(jw);
713}729}
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
715void zig_print_analysis_dump(CodeGen *g, FILE *f, const char *one_indent, const char *nl) {775void zig_print_analysis_dump(CodeGen *g, FILE *f, const char *one_indent, const char *nl) {
716 Error err;776 Error err;
717 AnalDumpCtx ctx = {};777 AnalDumpCtx ctx = {};
...@@ -722,6 +782,7 @@ void zig_print_analysis_dump(CodeGen *g, FILE *f, const char *one_indent, const...@@ -722,6 +782,7 @@ void zig_print_analysis_dump(CodeGen *g, FILE *f, const char *one_indent, const
722 ctx.pkg_map.init(16);782 ctx.pkg_map.init(16);
723 ctx.file_map.init(16);783 ctx.file_map.init(16);
724 ctx.decl_map.init(16);784 ctx.decl_map.init(16);
785 ctx.node_map.init(16);
725786
726 jw_begin_object(jw);787 jw_begin_object(jw);
727788
...@@ -794,5 +855,14 @@ void zig_print_analysis_dump(CodeGen *g, FILE *f, const char *one_indent, const...@@ -794,5 +855,14 @@ void zig_print_analysis_dump(CodeGen *g, FILE *f, const char *one_indent, const
794 }855 }
795 jw_end_array(jw);856 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
797 jw_end_object(jw);867 jw_end_object(jw);
798}868}
src/parser.cpp+2-2
...@@ -503,9 +503,9 @@ static Token *ast_parse_doc_comments(ParseContext *pc, Buf *buf) {...@@ -503,9 +503,9 @@ static Token *ast_parse_doc_comments(ParseContext *pc, Buf *buf) {
503 if (buf->list.length == 0) {503 if (buf->list.length == 0) {
504 buf_resize(buf, 0);504 buf_resize(buf, 0);
505 }505 }
506 // chops off '///' and '\n'506 // chops off '///' but leaves '\n'
507 buf_append_mem(buf, buf_ptr(pc->buf) + doc_token->start_pos + 3,507 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);
509 }509 }
510 return doc_token;510 return doc_token;
511}511}