From 17613185e79b324948c14257f64c388c8e2a52fb Mon Sep 17 00:00:00 2001 From: gingerBill Date: Tue, 4 Jan 2022 11:44:34 +0000 Subject: Support struct field tags in odin doc format --- src/docs_writer.cpp | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'src/docs_writer.cpp') diff --git a/src/docs_writer.cpp b/src/docs_writer.cpp index e8e8892ec..56ad0561e 100644 --- a/src/docs_writer.cpp +++ b/src/docs_writer.cpp @@ -598,6 +598,15 @@ OdinDocTypeIndex odin_doc_type(OdinDocWriter *w, Type *type) { } doc_type.where_clauses = odin_doc_where_clauses(w, st->where_clauses); } + + auto tags = array_make(heap_allocator(), type->Struct.fields.count); + defer (array_free(&tags)); + + for_array(i, type->Struct.fields) { + tags[i] = odin_doc_write_string(w, type->Struct.tags[i]); + } + + doc_type.tags = odin_write_slice(w, tags.data, tags.count); } break; case Type_Union: -- cgit v1.2.3 From 686dbb4421824f17164443b2538b587e91d400a5 Mon Sep 17 00:00:00 2001 From: gingerBill Date: Mon, 17 Jan 2022 14:43:42 +0000 Subject: Correct odin doc comment printing --- src/docs.cpp | 28 ++++++++++++++++++++++------ src/docs_writer.cpp | 5 +++-- 2 files changed, 25 insertions(+), 8 deletions(-) (limited to 'src/docs_writer.cpp') diff --git a/src/docs.cpp b/src/docs.cpp index 8d65cb83a..3ea3cce1b 100644 --- a/src/docs.cpp +++ b/src/docs.cpp @@ -67,6 +67,14 @@ GB_COMPARE_PROC(cmp_ast_package_by_name) { #include "docs_format.cpp" #include "docs_writer.cpp" +void print_doc_line(i32 indent, String const &data) { + while (indent --> 0) { + gb_printf("\t"); + } + gb_file_write(gb_file_get_standard(gbFileStandard_Output), data.text, data.len); + gb_printf("\n"); +} + void print_doc_line(i32 indent, char const *fmt, ...) { while (indent --> 0) { gb_printf("\t"); @@ -86,6 +94,13 @@ void print_doc_line_no_newline(i32 indent, char const *fmt, ...) { gb_printf_va(fmt, va); va_end(va); } +void print_doc_line_no_newline(i32 indent, String const &data) { + while (indent --> 0) { + gb_printf("\t"); + } + gb_file_write(gb_file_get_standard(gbFileStandard_Output), data.text, data.len); +} + bool print_doc_comment_group_string(i32 indent, CommentGroup *g) { if (g == nullptr) { @@ -106,8 +121,9 @@ bool print_doc_comment_group_string(i32 indent, CommentGroup *g) { String comment = g->list[i].string; String original_comment = comment; - bool slash_slash = comment[1] == '/'; + bool slash_slash = false; if (comment[1] == '/') { + slash_slash = true; comment.text += 2; comment.len -= 2; } else if (comment[1] == '*') { @@ -131,7 +147,7 @@ bool print_doc_comment_group_string(i32 indent, CommentGroup *g) { } if (slash_slash) { - print_doc_line(indent, "%.*s", LIT(comment)); + print_doc_line(indent, comment); count += 1; } else { isize pos = 0; @@ -143,7 +159,7 @@ bool print_doc_comment_group_string(i32 indent, CommentGroup *g) { } } String line = substring(comment, pos, end); - pos = end+1; + pos = end; String trimmed_line = string_trim_whitespace(line); if (trimmed_line.len == 0) { if (count == 0) { @@ -159,7 +175,7 @@ bool print_doc_comment_group_string(i32 indent, CommentGroup *g) { line = substring(line, 2, line.len); } - print_doc_line(indent, "%.*s", LIT(line)); + print_doc_line(indent, line); count += 1; } } @@ -263,7 +279,7 @@ void print_doc_package(CheckerInfo *info, AstPackage *pkg) { } GB_ASSERT(type_expr != nullptr || init_expr != nullptr); - print_doc_line_no_newline(2, "%.*s", LIT(e->token.string)); + print_doc_line_no_newline(2, e->token.string); if (type_expr != nullptr) { gbString t = expr_to_string(type_expr); gb_printf(": %s ", t); @@ -298,7 +314,7 @@ void print_doc_package(CheckerInfo *info, AstPackage *pkg) { for_array(i, pkg->files) { AstFile *f = pkg->files[i]; String filename = remove_directory_from_path(f->fullpath); - print_doc_line(2, "%.*s", LIT(filename)); + print_doc_line(2, filename); } } diff --git a/src/docs_writer.cpp b/src/docs_writer.cpp index 56ad0561e..94b43be99 100644 --- a/src/docs_writer.cpp +++ b/src/docs_writer.cpp @@ -292,8 +292,9 @@ bool odin_doc_append_comment_group_string(Array *buf, CommentGroup *g) { String comment = g->list[i].string; String original_comment = comment; - bool slash_slash = comment[1] == '/'; + bool slash_slash = false; if (comment[1] == '/') { + slash_slash = true; comment.text += 2; comment.len -= 2; } else if (comment[1] == '*') { @@ -330,7 +331,7 @@ bool odin_doc_append_comment_group_string(Array *buf, CommentGroup *g) { } } String line = substring(comment, pos, end); - pos = end+1; + pos = end; String trimmed_line = string_trim_whitespace(line); if (trimmed_line.len == 0) { if (count == 0) { -- cgit v1.2.3 From fb01dfe04845a489760956cea4f0019e1464b2e3 Mon Sep 17 00:00:00 2001 From: gingerBill Date: Mon, 17 Jan 2022 22:17:07 +0000 Subject: Improve docs_writer.cpp --- core/math/big/doc.odin | 22 ---------------------- core/math/big/internal.odin | 24 +++++++++++++++++++++++- core/math/big/tune.odin | 3 +-- src/docs_writer.cpp | 2 +- src/types.cpp | 14 +++++--------- 5 files changed, 30 insertions(+), 35 deletions(-) (limited to 'src/docs_writer.cpp') diff --git a/core/math/big/doc.odin b/core/math/big/doc.odin index f5e0900f5..0f9b88d01 100644 --- a/core/math/big/doc.odin +++ b/core/math/big/doc.odin @@ -2,27 +2,5 @@ A BigInt implementation in Odin. For the theoretical underpinnings, see Knuth's The Art of Computer Programming, Volume 2, section 4.3. The code started out as an idiomatic source port of libTomMath, which is in the public domain, with thanks. - -========================== Low-level routines ========================== - -IMPORTANT: `internal_*` procedures make certain assumptions about their input. - -The public functions that call them are expected to satisfy their sanity check requirements. -This allows `internal_*` call `internal_*` without paying this overhead multiple times. - -Where errors can occur, they are of course still checked and returned as appropriate. - -When importing `math:core/big` to implement an involved algorithm of your own, you are welcome -to use these procedures instead of their public counterparts. - -Most inputs and outputs are expected to be passed an initialized `Int`, for example. -Exceptions include `quotient` and `remainder`, which are allowed to be `nil` when the calling code doesn't need them. - -Check the comments above each `internal_*` implementation to see what constraints it expects to have met. - -We pass the custom allocator to procedures by default using the pattern `context.allocator = allocator`. -This way we don't have to add `, allocator` at the end of each call. - -TODO: Handle +/- Infinity and NaN. */ package math_big diff --git a/core/math/big/internal.odin b/core/math/big/internal.odin index 5085898e5..dbcd16509 100644 --- a/core/math/big/internal.odin +++ b/core/math/big/internal.odin @@ -1,10 +1,32 @@ -//+ignore /* Copyright 2021 Jeroen van Rijn . Made available under Odin's BSD-3 license. + + ========================== Low-level routines ========================== + + IMPORTANT: `internal_*` procedures make certain assumptions about their input. + + The public functions that call them are expected to satisfy their sanity check requirements. + This allows `internal_*` call `internal_*` without paying this overhead multiple times. + + Where errors can occur, they are of course still checked and returned as appropriate. + + When importing `math:core/big` to implement an involved algorithm of your own, you are welcome + to use these procedures instead of their public counterparts. + + Most inputs and outputs are expected to be passed an initialized `Int`, for example. + Exceptions include `quotient` and `remainder`, which are allowed to be `nil` when the calling code doesn't need them. + + Check the comments above each `internal_*` implementation to see what constraints it expects to have met. + + We pass the custom allocator to procedures by default using the pattern `context.allocator = allocator`. + This way we don't have to add `, allocator` at the end of each call. + + TODO: Handle +/- Infinity and NaN. */ +//+ignore package math_big import "core:mem" diff --git a/core/math/big/tune.odin b/core/math/big/tune.odin index 64a73b656..78a20c12b 100644 --- a/core/math/big/tune.odin +++ b/core/math/big/tune.odin @@ -1,4 +1,3 @@ -//+ignore /* Copyright 2021 Jeroen van Rijn . Made available under Odin's BSD-3 license. @@ -8,7 +7,7 @@ The code started out as an idiomatic source port of libTomMath, which is in the public domain, with thanks. */ - +//+ignore package math_big import "core:time" diff --git a/src/docs_writer.cpp b/src/docs_writer.cpp index 94b43be99..762a2afe1 100644 --- a/src/docs_writer.cpp +++ b/src/docs_writer.cpp @@ -513,7 +513,7 @@ OdinDocTypeIndex odin_doc_type(OdinDocWriter *w, Type *type) { break; case Type_Generic: doc_type.kind = OdinDocType_Generic; - doc_type.name = odin_doc_write_string(w, type->Generic.name); + doc_type.name = odin_doc_write_string(w, type->Generic.entity->token.string); if (type->Generic.specialized) { doc_type.types = odin_doc_type_as_slice(w, type->Generic.specialized); } diff --git a/src/types.cpp b/src/types.cpp index f621d4346..6162a5aa8 100644 --- a/src/types.cpp +++ b/src/types.cpp @@ -3933,7 +3933,7 @@ gbString write_type_to_string(gbString str, Type *type) { str = gb_string_appendc(str, " = "); str = write_exact_value_to_string(str, var->Constant.value); } else { - str = gb_string_appendc(str, "="); + str = gb_string_appendc(str, " := "); str = write_exact_value_to_string(str, var->Constant.value); } continue; @@ -3961,14 +3961,10 @@ gbString write_type_to_string(gbString str, Type *type) { str = gb_string_appendc(str, "typeid/"); str = write_type_to_string(str, var->type); } else { - if (var->kind == Entity_TypeName) { - str = gb_string_appendc(str, "$"); - str = gb_string_append_length(str, name.text, name.len); - str = gb_string_appendc(str, "="); - str = write_type_to_string(str, var->type); - } else { - str = gb_string_appendc(str, "typeid"); - } + str = gb_string_appendc(str, "$"); + str = gb_string_append_length(str, name.text, name.len); + str = gb_string_appendc(str, "="); + str = write_type_to_string(str, var->type); } } } -- cgit v1.2.3 From 28a816ef25476086800a294202aad7c1a1bfc0f0 Mon Sep 17 00:00:00 2001 From: gingerBill Date: Wed, 19 Jan 2022 14:57:27 +0000 Subject: Allow for entity grouping in structs and procedure signatures with the Odin doc-format --- core/odin/doc-format/doc_format.odin | 6 +- src/check_type.cpp | 13 +++ src/docs_format.cpp | 3 +- src/docs_writer.cpp | 20 ++++- src/entity.cpp | 2 + tools/odin-html-docs/odin_html_docs_main.odin | 121 +++++++++++++++----------- tools/odin-html-docs/style.css | 13 ++- 7 files changed, 119 insertions(+), 59 deletions(-) (limited to 'src/docs_writer.cpp') diff --git a/core/odin/doc-format/doc_format.odin b/core/odin/doc-format/doc_format.odin index 83cd89ca2..5e869ff73 100644 --- a/core/odin/doc-format/doc_format.odin +++ b/core/odin/doc-format/doc_format.odin @@ -11,7 +11,7 @@ String :: distinct Array(byte) Version_Type_Major :: 0 Version_Type_Minor :: 2 -Version_Type_Patch :: 2 +Version_Type_Patch :: 3 Version_Type :: struct { major, minor, patch: u8, @@ -122,6 +122,10 @@ Entity :: struct { _: u32le, // reserved for init comment: String, docs: String, + // May be used by (Struct fields and procedure fields): + // .Variable + // .Constant + field_group_index: i32le, // May used by: // .Variable diff --git a/src/check_type.cpp b/src/check_type.cpp index 5389252b3..a5a757f3e 100644 --- a/src/check_type.cpp +++ b/src/check_type.cpp @@ -109,11 +109,14 @@ void check_struct_fields(CheckerContext *ctx, Ast *node, Slice *fields } i32 field_src_index = 0; + i32 field_group_index = -1; for_array(i, params) { Ast *param = params[i]; if (param->kind != Ast_Field) { continue; } + field_group_index += 1; + ast_node(p, Field, param); Ast *type_expr = p->type; Type *type = nullptr; @@ -152,6 +155,7 @@ void check_struct_fields(CheckerContext *ctx, Ast *node, Slice *fields Entity *field = alloc_entity_field(ctx->scope, name_token, type, is_using, field_src_index); add_entity(ctx, ctx->scope, name, field); + field->Variable.field_group_index = field_group_index; array_add(&fields_array, field); String tag = p->tag.string; if (tag.len != 0 && !unquote_string(permanent_allocator(), &tag, 0, tag.text[0] == '`')) { @@ -1366,11 +1370,13 @@ Type *check_get_params(CheckerContext *ctx, Scope *scope, Ast *_params, bool *is isize variadic_index = -1; bool is_c_vararg = false; auto variables = array_make(permanent_allocator(), 0, variable_count); + i32 field_group_index = -1; for_array(i, params) { Ast *param = params[i]; if (param->kind != Ast_Field) { continue; } + field_group_index += 1; ast_node(p, Field, param); Ast *type_expr = unparen_expr(p->type); Type *type = nullptr; @@ -1671,9 +1677,11 @@ Type *check_get_params(CheckerContext *ctx, Scope *scope, Ast *_params, bool *is } param = alloc_entity_const_param(scope, name->Ident.token, type, poly_const, is_type_polymorphic(type)); + param->Constant.field_group_index = field_group_index; } else { param = alloc_entity_param(scope, name->Ident.token, type, is_using, true); param->Variable.param_value = param_value; + param->Variable.field_group_index = field_group_index; } } if (p->flags&FieldFlag_no_alias) { @@ -1767,7 +1775,10 @@ Type *check_get_results(CheckerContext *ctx, Scope *scope, Ast *_results) { } auto variables = array_make(permanent_allocator(), 0, variable_count); + i32 field_group_index = -1; for_array(i, results) { + field_group_index += 1; + ast_node(field, Field, results[i]); Ast *default_value = unparen_expr(field->default_value); ParameterValue param_value = {}; @@ -1798,6 +1809,7 @@ Type *check_get_results(CheckerContext *ctx, Scope *scope, Ast *_results) { token.string = str_lit(""); Entity *param = alloc_entity_param(scope, token, type, false, false); param->Variable.param_value = param_value; + param->Variable.field_group_index = -1; array_add(&variables, param); } else { for_array(j, field->names) { @@ -1821,6 +1833,7 @@ Type *check_get_results(CheckerContext *ctx, Scope *scope, Ast *_results) { Entity *param = alloc_entity_param(scope, token, type, false, false); param->flags |= EntityFlag_Result; param->Variable.param_value = param_value; + param->Variable.field_group_index = field_group_index; array_add(&variables, param); add_entity(ctx, scope, name, param); // NOTE(bill): Removes `declared but not used` when using -vet diff --git a/src/docs_format.cpp b/src/docs_format.cpp index 5cfac4817..38e7e20c2 100644 --- a/src/docs_format.cpp +++ b/src/docs_format.cpp @@ -15,7 +15,7 @@ struct OdinDocVersionType { #define OdinDocVersionType_Major 0 #define OdinDocVersionType_Minor 2 -#define OdinDocVersionType_Patch 2 +#define OdinDocVersionType_Patch 3 struct OdinDocHeaderBase { u8 magic[8]; @@ -185,6 +185,7 @@ struct OdinDocEntity { u32 reserved_for_init; OdinDocString comment; OdinDocString docs; + i32 field_group_index; OdinDocEntityIndex foreign_library; OdinDocString link_name; OdinDocArray attributes; diff --git a/src/docs_writer.cpp b/src/docs_writer.cpp index 762a2afe1..c4a0cd27f 100644 --- a/src/docs_writer.cpp +++ b/src/docs_writer.cpp @@ -512,10 +512,16 @@ OdinDocTypeIndex odin_doc_type(OdinDocWriter *w, Type *type) { doc_type.entities = odin_doc_add_entity_as_slice(w, type->Named.type_name); break; case Type_Generic: - doc_type.kind = OdinDocType_Generic; - doc_type.name = odin_doc_write_string(w, type->Generic.entity->token.string); - if (type->Generic.specialized) { - doc_type.types = odin_doc_type_as_slice(w, type->Generic.specialized); + { + String name = type->Generic.name; + if (type->Generic.entity) { + name = type->Generic.entity->token.string; + } + doc_type.kind = OdinDocType_Generic; + doc_type.name = odin_doc_write_string(w, name); + if (type->Generic.specialized) { + doc_type.types = odin_doc_type_as_slice(w, type->Generic.specialized); + } } break; case Type_Pointer: @@ -810,6 +816,7 @@ OdinDocEntityIndex odin_doc_add_entity(OdinDocWriter *w, Entity *e) { OdinDocEntityKind kind = OdinDocEntity_Invalid; u32 flags = 0; + i32 field_group_index = -1; switch (e->kind) { case Entity_Invalid: kind = OdinDocEntity_Invalid; break; @@ -839,6 +846,10 @@ OdinDocEntityIndex odin_doc_add_entity(OdinDocWriter *w, Entity *e) { if (init_expr == nullptr) { init_expr = e->Variable.init_expr; } + field_group_index = e->Variable.field_group_index; + break; + case Entity_Constant: + field_group_index = e->Constant.field_group_index; break; case Entity_Procedure: if (e->Procedure.is_foreign) { flags |= OdinDocEntityFlag_Foreign; } @@ -883,6 +894,7 @@ OdinDocEntityIndex odin_doc_add_entity(OdinDocWriter *w, Entity *e) { doc_entity.init_string = init_string; doc_entity.comment = odin_doc_comment_group_string(w, comment); doc_entity.docs = odin_doc_comment_group_string(w, docs); + doc_entity.field_group_index = field_group_index; doc_entity.foreign_library = 0; // Set later doc_entity.link_name = odin_doc_write_string(w, link_name); if (e->decl_info != nullptr) { diff --git a/src/entity.cpp b/src/entity.cpp index b39ffc63a..05ee9a33e 100644 --- a/src/entity.cpp +++ b/src/entity.cpp @@ -160,10 +160,12 @@ struct Entity { ExactValue value; ParameterValue param_value; u32 flags; + i32 field_group_index; } Constant; struct { Ast *init_expr; // only used for some variables within procedure bodies i32 field_index; + i32 field_group_index; ParameterValue param_value; diff --git a/tools/odin-html-docs/odin_html_docs_main.odin b/tools/odin-html-docs/odin_html_docs_main.odin index a2d516812..e196aa236 100644 --- a/tools/odin-html-docs/odin_html_docs_main.odin +++ b/tools/odin-html-docs/odin_html_docs_main.odin @@ -10,6 +10,7 @@ import "core:sort" import "core:slice" GITHUB_CORE_URL :: "https://github.com/odin-lang/Odin/tree/master/core" +BASE_CORE_URL :: "/core" header: ^doc.Header files: []doc.File @@ -96,7 +97,7 @@ write_html_footer :: proc(w: io.Writer, include_directory_js: bool) { io.write(w, #load("footer.txt.html")) - if include_directory_js { + if false && include_directory_js { io.write_string(w, `