From: Brendan Hansen Date: Wed, 29 Mar 2023 22:56:29 +0000 (-0500) Subject: added: more documentation; bugfix: aliased type names X-Git-Url: https://git.brendanfh.com/?a=commitdiff_plain;h=refs%2Fheads%2Fdocgen;p=onyx.git added: more documentation; bugfix: aliased type names --- diff --git a/compiler/src/doc.c b/compiler/src/doc.c index 6e250577..5e52c7f9 100644 --- a/compiler/src/doc.c +++ b/compiler/src/doc.c @@ -341,6 +341,14 @@ static void write_type_node(bh_buffer *buffer, void *vnode) { bh_buffer_write_string(buffer, "_TYPEOF_"); return; + case Ast_Kind_Alias: + write_type_node(buffer, ((AstAlias *) node)->alias); + return; + + case Ast_Kind_Type_Alias: + write_type_node(buffer, ((AstTypeAlias *) node)->to); + return; + case Ast_Kind_Symbol: case Ast_Kind_Param: if (node->flags & Ast_Flag_Symbol_Is_PolyVar) diff --git a/compiler/src/onyx.c b/compiler/src/onyx.c index 43ff6a5c..5a715d7c 100644 --- a/compiler/src/onyx.c +++ b/compiler/src/onyx.c @@ -57,9 +57,9 @@ static const char *build_docstring = DOCSTRING_HEADER "\t--wasm-mvp Use only WebAssembly MVP features.\n" "\t--multi-threaded Enables multi-threading for this compilation.\n" "\t Automatically enabled for \"onyx\" runtime.\n" + "\t--doc Generates an O-DOC file, a.k.a an Onyx documentation file. Used by onyx-doc-gen.\n" "\t--tag Generates a C-Tag file.\n" "\t--syminfo Generates a symbol resolution information file. Used by onyx-lsp.\n" - "\t--doc \n" "\t--generate-foreign-info\n" "\n" "Developer options:\n" diff --git a/core/alloc/alloc.onyx b/core/alloc/alloc.onyx index 0577b32b..f08b3058 100644 --- a/core/alloc/alloc.onyx +++ b/core/alloc/alloc.onyx @@ -12,7 +12,11 @@ as_allocator :: #match { macro (a: Allocator) => a } -// This is similar to alloca in C. +#doc """ + Allocates memory from the stack. This is similar to `alloca` in C. + + **DO NOT USE THIS IN A LOOP! You cannot free memory allocated off the stack.** +""" from_stack :: macro (size: u32) -> rawptr { // This should do something about the alignment... // Everything so far has assume that the stack is aligned to 16 bytes. @@ -20,11 +24,26 @@ from_stack :: macro (size: u32) -> rawptr { return __stack_top; } +#doc """ + Allocates memory from the stack to form a slice of `T` with length `size`. + + **DO NOT USE THIS IN A LOOP! You cannot free memory allocated off the stack.** +""" array_from_stack :: macro ($T: type_expr, size: u32) -> [] T { defer __stack_top = cast([&]u8, __stack_top) + size * sizeof T; return (cast([&]T) __stack_top)[0 .. size]; } +#doc """ + Moves a value on to the heap. Useful for cases like this: + + f :: () -> &Foo { + return alloc.on_heap(Foo.{ + name = "...", + age = 42 + }); + } +""" on_heap :: macro (v: $V) -> &V { out := cast(&V) raw_alloc(context.allocator, sizeof V); core.memory.set(out, 0, sizeof V); @@ -32,6 +51,9 @@ on_heap :: macro (v: $V) -> &V { return out; } +#doc """ + Like `alloc.on_heap`, but allocates on the temporary allocator. +""" on_temp :: macro (v: $V) -> &V { out := cast(&V) raw_alloc(context.temp_allocator, sizeof V); core.memory.set(out, 0, sizeof V); diff --git a/core/alloc/arena.onyx b/core/alloc/arena.onyx index e155800d..61ea8681 100644 --- a/core/alloc/arena.onyx +++ b/core/alloc/arena.onyx @@ -128,7 +128,7 @@ free :: (arena: &Arena) { arena.size = 0; } -// Clears and frees every page, except for first page. +#doc "Clears and frees every page, except for first page." clear :: (arena: &Arena) { walker := arena.first_arena.next; while walker != null { diff --git a/core/encoding/csv.onyx b/core/encoding/csv.onyx index a5afd72b..c3a636a6 100644 --- a/core/encoding/csv.onyx +++ b/core/encoding/csv.onyx @@ -24,29 +24,27 @@ use runtime.info { Type_Info_Struct } -// -// Represents data from a CSV file of a particular type. +#doc "Represents data from a CSV file of a particular type." CSV :: struct (Output_Type: type_expr) { entries: [..] Output_Type; } -// -// Tag-type used to tell the ingress and egress methods what -// the column name of a particular data element should be. -// -// Data :: struct { -// @CSV_Column.{"Actual Column Name"} -// variable_name: str; -// } +#doc """ + Tag-type used to tell the ingress and egress methods what + the column name of a particular data element should be. + + Data :: struct { + @CSV_Column.{"Actual Column Name"} + variable_name: str; + } +""" CSV_Column :: struct { name: str; } -// -// Define methods used with the CSV structure. +#doc "Define methods used with the CSV structure." #inject CSV { - // - // Create and initialize a CSV with no elements. + #doc "Create and initialize a CSV with no elements." make :: ($T: type_expr) => { r := CSV(T).{}; r.entries = make(typeof r.entries); @@ -54,19 +52,19 @@ CSV_Column :: struct { return r; } - // - // Frees all data in a CSV. + #doc "Frees all data in a CSV." delete :: (csv: &CSV) { delete(&csv.entries); } - // - // Ingests data from a string representing CSV data. - // Uses the type of the CSV to know what columns should be expected. - // If `headers_presents` is true, the first line will be treated as - // headers, and cross checked with the CSV_Column tag information. - // Use this when the columns from your CSV have a different order - // from the order of fields in the structure. + #doc """ + Ingests data from a string representing CSV data. + Uses the type of the CSV to know what columns should be expected. + If `headers_presents` is true, the first line will be treated as + headers, and cross checked with the CSV_Column tag information. + Use this when the columns from your CSV have a different order + from the order of fields in the structure. + """ ingress_string :: (csv: &CSV, contents: str, headers_present := true) -> bool { reader, stream := io.reader_from_string(contents); defer cfree(stream); @@ -74,9 +72,10 @@ CSV_Column :: struct { return csv->ingress(&reader, headers_present); } - // - // Ingests data from an Reader containing CSV data. - // Uses the type of the CSV to know what columns should be expectd. + #doc """ + Ingests data from a Reader containing CSV data. + Uses the type of the CSV to know what columns should be expectd. + """ ingress :: (csv: &CSV, reader: &io.Reader, headers_present := true) -> bool { Header :: struct { type: type_expr; @@ -132,10 +131,11 @@ CSV_Column :: struct { } } - // - // Outputs data from a CSV into a Writer. - // When `include_headers` is true, the first line outputted will be - // the headers of the CSV, according to the CSV_Column tag information. + #doc """ + Outputs data from a CSV into a Writer. + When `include_headers` is true, the first line outputted will be + the headers of the CSV, according to the CSV_Column tag information. + """ egress :: (csv: &CSV, writer: &io.Writer, include_headers := true) { output_type_info: &Type_Info_Struct = ~~ get_type_info(csv.Output_Type);