added: more documentation; bugfix: aliased type names

diff --git a/compiler/src/doc.c b/compiler/src/doc.c
index 6e2505773ede1a1e964b991441ee5bec6ff92ba8..5e52c7f9f056b24d684920f73995b1da408a7ec7 100644 (file)
--- 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 43ff6a5c11b4bf0b94511ff4c65a8090ac1bd298..5a715d7c07d63e6c39afa1a07d19316a1fefdec7 100644 (file)
--- 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 <doc_file>        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 <target_file> Generates a symbol resolution information file. Used by onyx-lsp.\n"
-    "\t--doc <doc_file>\n"
     "\t--generate-foreign-info\n"
     "\n"
     "Developer options:\n"

diff --git a/core/alloc/alloc.onyx b/core/alloc/alloc.onyx
index 0577b32b13051d7cfe95ec25e3d8132480a8d609..f08b305878d49081e01136f19c6382c8032d6c50 100644 (file)
--- 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 e155800d765adc9536f069558ae7a46d9c5540ff..61ea86810b62bd79fb2dbfd39c87676b363bea9c 100644 (file)
--- 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 a5afd72b854429b3fb7444a009b81cf0cc45269a..c3a636a6d18dafd75aa617a076eb53fca1e1cdc0 100644 (file)
--- 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);