From ac7703f65f7acc9137e28ded97659fbaadea4e66 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Wed, 4 Sep 2019 11:08:28 -0400
Subject: [PATCH] fixups and add documentation for `@Type`

---
 doc/docgen.zig                | 26 ++++++++++++++--
 doc/langref.html.in           | 56 ++++++++++++++++++++++++++++++++++-
 src/all_types.hpp             |  8 +++++
 src/codegen.cpp               | 29 ++++++++++--------
 src/ir.cpp                    | 38 +++++++++++-------------
 test/compile_errors.zig       | 18 +++++------
 test/stage1/behavior/type.zig |  4 ---
 7 files changed, 130 insertions(+), 49 deletions(-)

diff --git a/doc/docgen.zig b/doc/docgen.zig
index a2b4e8501c..eee4c45369 100644
--- a/doc/docgen.zig
+++ b/doc/docgen.zig
@@ -321,6 +321,7 @@ fn genToc(allocator: *mem.Allocator, tokenizer: *Tokenizer) !Toc {
 
     var header_stack_size: usize = 0;
     var last_action = Action.Open;
+    var last_columns: ?u8 = null;
 
     var toc_buf = try std.Buffer.initSize(allocator, 0);
     defer toc_buf.deinit();
@@ -361,7 +362,23 @@ fn genToc(allocator: *mem.Allocator, tokenizer: *Tokenizer) !Toc {
                     _ = try eatToken(tokenizer, Token.Id.Separator);
                     const content_token = try eatToken(tokenizer, Token.Id.TagContent);
                     const content = tokenizer.buffer[content_token.start..content_token.end];
-                    _ = try eatToken(tokenizer, Token.Id.BracketClose);
+                    var columns: ?u8 = null;
+                    while (true) {
+                        const bracket_tok = tokenizer.next();
+                        switch (bracket_tok.id) {
+                            .BracketClose => break,
+                            .Separator => continue,
+                            .TagContent => {
+                                const param = tokenizer.buffer[bracket_tok.start..bracket_tok.end];
+                                if (mem.eql(u8, param, "3col")) {
+                                    columns = 3;
+                                } else {
+                                    return parseError(tokenizer, bracket_tok, "unrecognized header_open param: {}", param);
+                                }
+                            },
+                            else => return parseError(tokenizer, bracket_tok, "invalid header_open token"),
+                        }
+                    }
 
                     header_stack_size += 1;
 
@@ -381,10 +398,15 @@ fn genToc(allocator: *mem.Allocator, tokenizer: *Tokenizer) !Toc {
                     if (last_action == Action.Open) {
                         try toc.writeByte('\n');
                         try toc.writeByteNTimes(' ', header_stack_size * 4);
-                        try toc.write("<ul>\n");
+                        if (last_columns) |n| {
+                            try toc.print("<ul style=\"columns: {}\">\n", n);
+                        } else {
+                            try toc.write("<ul>\n");
+                        }
                     } else {
                         last_action = Action.Open;
                     }
+                    last_columns = columns;
                     try toc.writeByteNTimes(' ', 4 + header_stack_size * 4);
                     try toc.print("<li><a id=\"toc-{}\" href=\"#{}\">{}</a>", urlized, urlized, content);
                 } else if (mem.eql(u8, tag_name, "header_close")) {
diff --git a/doc/langref.html.in b/doc/langref.html.in
index 44b2256813..2ad86d653e 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -6323,7 +6323,7 @@ fn readFile(allocator: *Allocator, filename: []const u8) ![]u8 {
       {#header_close#}
 
       {#header_close#}
-      {#header_open|Builtin Functions#}
+      {#header_open|Builtin Functions|3col#}
       <p>
       Builtin functions are provided by the compiler and are prefixed with <code>@</code>.
       The {#syntax#}comptime{#endsyntax#} keyword on a parameter means that the parameter must be known
@@ -7232,6 +7232,9 @@ fn add(a: i32, b: i32) i32 { return a + b; }
       This function returns an integer type with the given signness and bit count. The maximum
       bit count for an integer type is {#syntax#}65535{#endsyntax#}.
       </p>
+      <p>
+      Deprecated. Use {#link|@Type#}.
+      </p>
       {#header_close#}
 
       {#header_open|@memberCount#}
@@ -7871,6 +7874,57 @@ test "integer truncation" {
       </p>
       {#header_close#}
 
+      {#header_open|@Type#}
+      <pre>{#syntax#}@Type(comptime info: @import("builtin").TypeInfo) type{#endsyntax#}</pre>
+      <p>
+      This function is the inverse of {#link|@typeInfo#}. It reifies type information
+      into a {#syntax#}type{#endsyntax#}.
+      </p>
+      <p>
+      It is available for the following types:
+      </p>
+      <ul>
+          <li>{#syntax#}type{#endsyntax#}</li>
+          <li>{#syntax#}noreturn{#endsyntax#}</li>
+          <li>{#syntax#}void{#endsyntax#}</li>
+          <li>{#syntax#}bool{#endsyntax#}</li>
+          <li>{#link|Integers#}</li> - The maximum bit count for an integer type is {#syntax#}65535{#endsyntax#}.
+          <li>{#link|Floats#}</li>
+          <li>{#link|Pointers#}</li>
+          <li>{#syntax#}comptime_int{#endsyntax#}</li>
+          <li>{#syntax#}comptime_float{#endsyntax#}</li>
+          <li>{#syntax#}@typeOf(undefined){#endsyntax#}</li>
+          <li>{#syntax#}@typeOf(null){#endsyntax#}</li>
+      </ul>
+      <p>
+      For these types it is a
+      <a href="https://github.com/ziglang/zig/issues/2907">TODO in the compiler to implement</a>:
+      </p>
+      <ul>
+          <li>Array</li>
+          <li>Optional</li>
+          <li>ErrorUnion</li>
+          <li>ErrorSet</li>
+          <li>Enum</li>
+          <li>Opaque</li>
+          <li>FnFrame</li>
+          <li>AnyFrame</li>
+          <li>Vector</li>
+          <li>EnumLiteral</li>
+      </ul>
+      <p>
+      For these types, {#syntax#}@Type{#endsyntax#} is not available.
+      <a href="https://github.com/ziglang/zig/issues/383">There is an open proposal to allow unions and structs</a>.
+      </p>
+      <ul>
+          <li>{#link|union#}</li>
+          <li>{#link|Functions#}</li>
+          <li>BoundFn</li>
+          <li>ArgTuple</li>
+          <li>{#link|struct#}</li>
+      </ul>
+      {#header_close#}
+
       {#header_open|@typeId#}
       <pre>{#syntax#}@typeId(comptime T: type) @import("builtin").TypeId{#endsyntax#}</pre>
       <p>
diff --git a/src/all_types.hpp b/src/all_types.hpp
index 4253a346f8..03559ccf12 100644
--- a/src/all_types.hpp
+++ b/src/all_types.hpp
@@ -54,6 +54,14 @@ enum PtrLen {
     PtrLenC,
 };
 
+// This one corresponds to the builtin.zig enum.
+enum BuiltinPtrSize {
+    BuiltinPtrSizeOne,
+    BuiltinPtrSizeMany,
+    BuiltinPtrSizeSlice,
+    BuiltinPtrSizeC,
+};
+
 enum UndefAllowed {
     UndefOk,
     UndefBad,
diff --git a/src/codegen.cpp b/src/codegen.cpp
index d7d4b44437..13fb0d625d 100644
--- a/src/codegen.cpp
+++ b/src/codegen.cpp
@@ -8161,20 +8161,25 @@ Buf *codegen_generate_builtin_source(CodeGen *g) {
             "        };\n"
             "    };\n"
             "};\n\n");
-        assert(ContainerLayoutAuto == 0);
-        assert(ContainerLayoutExtern == 1);
-        assert(ContainerLayoutPacked == 2);
+        static_assert(ContainerLayoutAuto == 0, "");
+        static_assert(ContainerLayoutExtern == 1, "");
+        static_assert(ContainerLayoutPacked == 2, "");
 
-        assert(CallingConventionUnspecified == 0);
-        assert(CallingConventionC == 1);
-        assert(CallingConventionCold == 2);
-        assert(CallingConventionNaked == 3);
-        assert(CallingConventionStdcall == 4);
-        assert(CallingConventionAsync == 5);
+        static_assert(CallingConventionUnspecified == 0, "");
+        static_assert(CallingConventionC == 1, "");
+        static_assert(CallingConventionCold == 2, "");
+        static_assert(CallingConventionNaked == 3, "");
+        static_assert(CallingConventionStdcall == 4, "");
+        static_assert(CallingConventionAsync == 5, "");
 
-        assert(FnInlineAuto == 0);
-        assert(FnInlineAlways == 1);
-        assert(FnInlineNever == 2);
+        static_assert(FnInlineAuto == 0, "");
+        static_assert(FnInlineAlways == 1, "");
+        static_assert(FnInlineNever == 2, "");
+
+        static_assert(BuiltinPtrSizeOne == 0, "");
+        static_assert(BuiltinPtrSizeMany == 1, "");
+        static_assert(BuiltinPtrSizeSlice == 2, "");
+        static_assert(BuiltinPtrSizeC == 3, "");
     }
     {
         buf_appendf(contents,
diff --git a/src/ir.cpp b/src/ir.cpp
index 953467c185..9547b1ec61 100644
--- a/src/ir.cpp
+++ b/src/ir.cpp
@@ -20115,25 +20115,26 @@ static Error ir_make_type_info_decls(IrAnalyze *ira, IrInstruction *source_instr
     return ErrorNone;
 }
 
-static uint32_t ptr_len_to_size_enum_index(PtrLen ptr_len) {
+static BuiltinPtrSize ptr_len_to_size_enum_index(PtrLen ptr_len) {
     switch (ptr_len) {
         case PtrLenSingle:
-            return 0;
+            return BuiltinPtrSizeOne;
         case PtrLenUnknown:
-            return 1;
+            return BuiltinPtrSizeMany;
         case PtrLenC:
-            return 3;
+            return BuiltinPtrSizeC;
     }
     zig_unreachable();
 }
 
-static PtrLen size_enum_index_to_ptr_len(uint32_t size_enum_index) {
+static PtrLen size_enum_index_to_ptr_len(BuiltinPtrSize size_enum_index) {
     switch (size_enum_index) {
-        case 0:
+        case BuiltinPtrSizeOne:
             return PtrLenSingle;
-        case 1:
+        case BuiltinPtrSizeMany:
+        case BuiltinPtrSizeSlice:
             return PtrLenUnknown;
-        case 3:
+        case BuiltinPtrSizeC:
             return PtrLenC;
     }
     zig_unreachable();
@@ -20142,10 +20143,10 @@ static PtrLen size_enum_index_to_ptr_len(uint32_t size_enum_index) {
 static ConstExprValue *create_ptr_like_type_info(IrAnalyze *ira, ZigType *ptr_type_entry) {
     Error err;
     ZigType *attrs_type;
-    uint32_t size_enum_index;
+    BuiltinPtrSize size_enum_index;
     if (is_slice(ptr_type_entry)) {
         attrs_type = ptr_type_entry->data.structure.fields[slice_ptr_index].type_entry;
-        size_enum_index = 2;
+        size_enum_index = BuiltinPtrSizeSlice;
     } else if (ptr_type_entry->id == ZigTypeIdPointer) {
         attrs_type = ptr_type_entry;
         size_enum_index = ptr_len_to_size_enum_index(ptr_type_entry->data.pointer.ptr_len);
@@ -20892,21 +20893,16 @@ static ZigType *type_info_to_type(IrAnalyze *ira, IrInstruction *instruction, Zi
                 assert(payload->type == type_info_pointer_type);
                 ConstExprValue *size_value = get_const_field(ira, payload, "size", 0);
                 assert(size_value->type == ir_type_info_get_type(ira, "Size", type_info_pointer_type));
-                uint32_t size_enum_index = bigint_as_u32(&size_value->data.x_enum_tag);
-                PtrLen ptr_len;
-                if (size_enum_index == 2) {
-                    ptr_len = PtrLenUnknown; // TODO: is this right?
-                } else {
-                    ptr_len = size_enum_index_to_ptr_len(size_enum_index);
-                }
+                BuiltinPtrSize size_enum_index = (BuiltinPtrSize)bigint_as_u32(&size_value->data.x_enum_tag);
+                PtrLen ptr_len = size_enum_index_to_ptr_len(size_enum_index);
                 ZigType *ptr_type = get_pointer_to_type_extra(ira->codegen,
                     get_const_field_meta_type(ira, payload, "child", 4),
                     get_const_field_bool(ira, payload, "is_const", 1),
                     get_const_field_bool(ira, payload, "is_volatile", 2),
                     ptr_len,
                     bigint_as_u32(get_const_field_lit_int(ira, payload, "alignment", 3)),
-                    0, // bit_offset_in_host???
-                    0, // host_int_bytes???
+                    0, // bit_offset_in_host
+                    0, // host_int_bytes
                     get_const_field_bool(ira, payload, "is_allowzero", 5)
                 );
                 if (size_enum_index != 2)
@@ -20932,7 +20928,7 @@ static ZigType *type_info_to_type(IrAnalyze *ira, IrInstruction *instruction, Zi
         case ZigTypeIdVector:
         case ZigTypeIdEnumLiteral:
             ir_add_error(ira, instruction, buf_sprintf(
-                "TODO implement @Type forr 'TypeInfo.%s': see https://github.com/ziglang/zig/issues/2907\n", type_id_name(tagTypeId)));
+                "TODO implement @Type for 'TypeInfo.%s': see https://github.com/ziglang/zig/issues/2907", type_id_name(tagTypeId)));
             return nullptr;
         case ZigTypeIdUnion:
         case ZigTypeIdFn:
@@ -20940,7 +20936,7 @@ static ZigType *type_info_to_type(IrAnalyze *ira, IrInstruction *instruction, Zi
         case ZigTypeIdArgTuple:
         case ZigTypeIdStruct:
             ir_add_error(ira, instruction, buf_sprintf(
-                "@Type not availble for 'TypeInfo.%s'\n", type_id_name(tagTypeId)));
+                "@Type not availble for 'TypeInfo.%s'", type_id_name(tagTypeId)));
             return nullptr;
     }
     zig_unreachable();
diff --git a/test/compile_errors.zig b/test/compile_errors.zig
index 1438a59539..38fca5754d 100644
--- a/test/compile_errors.zig
+++ b/test/compile_errors.zig
@@ -2,6 +2,15 @@ const tests = @import("tests.zig");
 const builtin = @import("builtin");
 
 pub fn addCases(cases: *tests.CompileErrorContext) void {
+    cases.add(
+        "attempt to create 17 bit float type",
+        \\const builtin = @import("builtin");
+        \\comptime {
+        \\    _ = @Type(builtin.TypeInfo { .Float = builtin.TypeInfo.Float { .bits = 17 } });
+        \\}
+    ,
+        "tmp.zig:3:32: error: 17-bit float unsupported",
+    );
 
     cases.add(
         "wrong type for @Type",
@@ -45,15 +54,6 @@ pub fn addCases(cases: *tests.CompileErrorContext) void {
         "tmp.zig:2:15: error: @Type not availble for 'TypeInfo.Struct'",
     );
 
-    cases.add(
-        "array not implemented for @Type",
-        \\export fn entry() void {
-        \\    _ = @Type(@typeInfo(enum{x}));
-        \\}
-    ,
-        "tmp.zig:2:15: error: TODO implement @Type forr 'TypeInfo.Enum': see https://github.com/ziglang/zig/issues/2907",
-    );
-
     cases.add(
         "wrong type for result ptr to @asyncCall",
         \\export fn entry() void {
diff --git a/test/stage1/behavior/type.zig b/test/stage1/behavior/type.zig
index 318e07fbdf..5b2998f088 100644
--- a/test/stage1/behavior/type.zig
+++ b/test/stage1/behavior/type.zig
@@ -38,8 +38,6 @@ test "Type.Int" {
     testing.expect(u64 == @Type(TypeInfo { .Int = TypeInfo.Int { .is_signed = false, .bits = 64 } }));
     testing.expect(i64 == @Type(TypeInfo { .Int = TypeInfo.Int { .is_signed = true, .bits = 64 } }));
     testTypes([_]type {u8,u32,i64});
-    // TODO: should this work?
-    //testing.expect(u1 == @Type(TypeInfo.Int { .is_signed = false, .bits = 1 } ));
 }
 
 test "Type.Float" {
@@ -48,8 +46,6 @@ test "Type.Float" {
     testing.expect(f64  == @Type(TypeInfo { .Float = TypeInfo.Float { .bits = 64 } }));
     testing.expect(f128 == @Type(TypeInfo { .Float = TypeInfo.Float { .bits = 128 } }));
     testTypes([_]type {f16, f32, f64, f128});
-    // error: 17-bit float unsupported
-    //testing.expect(f16  == @Type(TypeInfo { .Float = TypeInfo.Float { .bits = 17 } }));
 }
 
 test "Type.Pointer" {