diff --git a/doc/docgen.zig b/doc/docgen.zig index 9ec827ff3..636f63380 100644 --- a/doc/docgen.zig +++ b/doc/docgen.zig @@ -290,12 +290,19 @@ const Code = struct { }; }; +const Link = struct { + url: []const u8, + name: []const u8, + token: Token, +}; + const Node = union(enum) { Content: []const u8, Nav, HeaderOpen: HeaderOpen, SeeAlso: []const SeeAlsoItem, Code: Code, + Link: Link, }; const Toc = struct { @@ -412,6 +419,31 @@ fn genToc(allocator: &mem.Allocator, tokenizer: &Tokenizer) -> %Toc { else => return parseError(tokenizer, see_also_tok, "invalid see_also token"), } } + } else if (mem.eql(u8, tag_name, "link")) { + _ = try eatToken(tokenizer, Token.Id.Separator); + const name_tok = try eatToken(tokenizer, Token.Id.TagContent); + const name = tokenizer.buffer[name_tok.start..name_tok.end]; + + const url_name = blk: { + const tok = tokenizer.next(); + switch (tok.id) { + Token.Id.BracketClose => break :blk name, + Token.Id.Separator => { + const explicit_text = try eatToken(tokenizer, Token.Id.TagContent); + _ = try eatToken(tokenizer, Token.Id.BracketClose); + break :blk tokenizer.buffer[explicit_text.start..explicit_text.end]; + }, + else => return parseError(tokenizer, tok, "invalid link token"), + } + }; + + try nodes.append(Node { + .Link = Link { + .url = try urlize(allocator, url_name), + .name = name, + .token = name_tok, + }, + }); } else if (mem.eql(u8, tag_name, "code_begin")) { _ = try eatToken(tokenizer, Token.Id.Separator); const code_kind_tok = try eatToken(tokenizer, Token.Id.TagContent); @@ -661,6 +693,12 @@ fn genHtml(allocator: &mem.Allocator, tokenizer: &Tokenizer, toc: &Toc, out: &io Node.Content => |data| { try out.write(data); }, + Node.Link => |info| { + if (!toc.urls.contains(info.url)) { + return parseError(tokenizer, info.token, "url not found: {}", info.url); + } + try out.print("{}", info.url, info.name); + }, Node.Nav => { try out.write(toc.toc); }, diff --git a/doc/langref.html.in b/doc/langref.html.in index 24cd77acc..3734d9ff7 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -33,7 +33,7 @@ .file { text-decoration: underline; } - pre { + code { font-size: 12pt; } @media screen and (min-width: 28.75em) { @@ -102,10 +102,14 @@ pub fn main() -> %void { {#code_begin|exe|hello#} const warn = @import("std").debug.warn; -pub fn main() -> %void { +pub fn main() -> void { warn("Hello, world!\n"); } {#code_end#} +

+ Note that we also left off the % from the return type. + In Zig, if your main function cannot fail, you may use the void return type. +

{#see_also|Values|@import|Errors|Root Source File#} {#header_close#} {#header_open|Source Encoding#} @@ -621,7 +625,6 @@ fn divide(a: i32, b: i32) -> i32 { {#header_close#} {#header_close#} {#header_open|Floats#} - {#header_close#} {#header_open|Float Literals#} {#code_begin|syntax#} const floating_point = 123.0E+77; @@ -668,6 +671,7 @@ pub fn main() -> %void { {#code_end#} {#see_also|@setFloatMode|Division by Zero#} {#header_close#} + {#header_close#} {#header_open|Operators#} {#header_open|Table of Operators#} @@ -690,13 +694,13 @@ pub fn main() -> %void { a += b a +%= b a -= b a -%= b a *= b a *%= b a /= b @@ -855,17 +859,17 @@ a /= b a %= b @@ -878,13 +882,13 @@ a %= b a <<= b a >>= b a &= b a |= b a ^= b
Addition.
    -
  • Can cause overflow for integers.
    • +
  • Can cause {#link|overflow|Default Operations#} for integers.
 @@ -708,7 +712,7 @@ a += b Wrapping Addition. @@ -725,13 +729,13 @@ a +%= b Subtraction.
    -
  • Can cause overflow for integers.
    • +
  • Can cause {#link|overflow|Default Operations#} for integers.
 @@ -743,7 +747,7 @@ a -= b Wrapping Subtraction. @@ -759,14 +763,14 @@ a -%= b 
-a
 Negation.
    -
  • Can cause overflow for integers.
    • +
  • Can cause {#link|overflow|Default Operations#} for integers.
 @@ -777,7 +781,7 @@ a -%= b 
-%a
 @@ -795,13 +799,13 @@ a -%= b Multiplication.
    -
  • Can cause overflow for integers.
    • +
  • Can cause {#link|overflow|Default Operations#} for integers.
 @@ -813,7 +817,7 @@ a *= b Wrapping Multiplication. @@ -830,19 +834,19 @@ a *%= b Divison.
    -
  • Can cause overflow for integers.
    • -
  • Can cause division by zero for integers.
    • -
  • Can cause division by zero for floats in FloatMode.Optimized Mode.
    • +
  • Can cause {#link|overflow|Default Operations#} for integers.
    • +
  • Can cause {#link|Division by Zero#} for integers.
    • +
  • Can cause {#link|Division by Zero#} for floats in {#link|FloatMode.Optimized Mode|Floating Point Operations#}.
  • For non-compile-time-known signed integers, must use - @divTrunc, - @divFloor, or - @divExact instead of /. + {#link|@divTrunc#}, + {#link|@divFloor#}, or + {#link|@divExact#} instead of /.
Remainder Division.
    -
  • Can cause division by zero for integers.
    • -
  • Can cause division by zero for floats in FloatMode.Optimized Mode.
    • +
  • Can cause {#link|Division by Zero#} for integers.
    • +
  • Can cause {#link|Division by Zero#} for floats in {#link|FloatMode.Optimized Mode|Floating Point Operations#}.
  • For non-compile-time-known signed integers, must use - @rem or - @mod instead of %. + {#link|@rem#} or + {#link|@mod#} instead of %.
Bit Shift Left. @@ -896,12 +900,12 @@ a <<= b Bit Shift Right.
    -
  • See also @shrExact.
    • +
  • See also {#link|@shrExact#}.
 @@ -913,7 +917,7 @@ a >>= b Bitwise AND. @@ -927,7 +931,7 @@ a &= b Bitwise OR. @@ -941,7 +945,7 @@ a |= b Bitwise XOR. @@ -954,7 +958,7 @@ a ^= b 
~a
 @@ -968,13 +972,13 @@ a ^= b 
a ?? b
 If a is null, returns b ("default value"), otherwise returns the unwrapped value of a. - Note that b may be a value of type noreturn. + Note that b may be a value of type {#link|noreturn#}. 
const value: ?u32 = null;
@@ -986,7 +990,7 @@ unwrapped == 1234
??a
 @@ -1003,13 +1007,13 @@ unwrapped == 1234 a catch |err| b If a is an error, returns b ("default value"), otherwise returns the unwrapped value of a. - Note that b may be a value of type noreturn. + Note that b may be a value of type {#link|noreturn#}. err is the error and is in scope of the expression b. @@ -1022,7 +1026,7 @@ unwrapped == 1234 
a and b
    -
  • bool
    • +
  • {#link|bool|Primitive Types#}
 @@ -1037,7 +1041,7 @@ unwrapped == 1234 
a or b
    -
  • bool
    • +
  • {#link|bool|Primitive Types#}
 @@ -1052,7 +1056,7 @@ unwrapped == 1234 
!a
    -
  • bool
    • +
  • {#link|bool|Primitive Types#}
 @@ -1066,10 +1070,10 @@ unwrapped == 1234 
a == b
    -
  • Integers
    • -
  • Floats
    • -
  • bool
    • -
  • type
    • +
  • {#link|Integers#}
    • +
  • {#link|Floats#}
    • +
  • {#link|bool|Primitive Types#}
    • +
  • {#link|type|Primitive Types#}
 @@ -1083,7 +1087,7 @@ unwrapped == 1234 
a == null
 @@ -1098,10 +1102,10 @@ value == null 
a != b
    -
  • Integers
    • -
  • Floats
    • -
  • bool
    • -
  • type
    • +
  • {#link|Integers#}
    • +
  • {#link|Floats#}
    • +
  • {#link|bool|Primitive Types#}
    • +
  • {#link|type|Primitive Types#}
 @@ -1115,8 +1119,8 @@ value == null 
a > b
 @@ -1130,8 +1134,8 @@ value == null 
a >= b
 @@ -1145,8 +1149,8 @@ value == null 
a < b
 @@ -1160,8 +1164,8 @@ value == null 
a <= b
 @@ -1175,13 +1179,13 @@ value == null 
a ++ b
 Array concatenation.
    -
  • Only available when a and b are compile-time known. +
  • Only available when a and b are {#link|compile-time known|comptime#}.
@@ -1196,13 +1200,13 @@ mem.eql(u32, together, []u32{1,2,3,4}) 
a ** b
 Array multiplication.
    -
  • Only available when a and b are compile-time known. +
  • Only available when a and b are {#link|compile-time known|comptime#}.
@@ -1215,7 +1219,7 @@ mem.eql(u8, pattern, "ababab") 
*a
 @@ -1504,7 +1508,7 @@ test "pointer child type" { Each type has an alignment - a number of bytes such that, when a value of the type is loaded from or stored to memory, the memory address must be evenly divisible by this number. You can use - @alignOf to find out this value for any type. + {#link|@alignOf#} to find out this value for any type.

Alignment depends on the CPU architecture, but is always a power of two, and @@ -1562,9 +1566,9 @@ test "function alignment" { {#code_end#}

If you have a pointer or a slice that has a small alignment, but you know that it actually - has a bigger alignment, use @alignCast to change the + has a bigger alignment, use {#link|@alignCast#} to change the pointer into a more aligned pointer. This is a no-op at runtime, but inserts a - safety check: + {#link|safety check|Incorrect Pointer Alignment#}:

{#code_begin|test_safety|incorrect alignment#} const assert = @import("std").debug.assert; @@ -1589,7 +1593,7 @@ fn foo(bytes: []u8) -> u32 {

As an example, this code produces undefined behavior:

*@ptrCast(&u32, f32(12.34))
-

Instead, use @bitCast: +

Instead, use {#link|@bitCast#}: 

@bitCast(u32, f32(12.34))

As an added benefit, the @bitcast version works at compile-time.

{#see_also|Slices|Memory#} @@ -3391,7 +3395,7 @@ test "fibonacci" { The compiler noticed that evaluating this function at compile-time took a long time, and thus emitted a compile error and gave up. If the programmer wants to increase the budget for compile-time computation, they can use a built-in function called - @setEvalBranchQuota to change the default number 1000 to something else. + {#link|@setEvalBranchQuota#} to change the default number 1000 to something else.

What if we fix the base case, but put the wrong value in the assert line? @@ -3750,7 +3754,7 @@ pub fn main() { ?fn(), or []T. It returns the same type as ptr except with the alignment adjusted to the new value.

-

A pointer alignment safety check is added +

A {#link|pointer alignment safety check|Incorrect Pointer Alignment#} is added to the generated code to make sure the pointer is aligned as promised.

{#header_close#} @@ -3767,7 +3771,7 @@ comptime { }

The result is a target-specific compile time constant. It is guaranteed to be - less than or equal to @sizeOf(T). + less than or equal to {#link|@sizeOf(T)|@sizeOf#}.

{#see_also|Alignment#} {#header_close#} @@ -4109,7 +4113,7 @@ fn add(a: i32, b: i32) -> i32 { return a + b; } {#header_open|@intToPtr#} 
@intToPtr(comptime DestType: type, int: usize) -> DestType

- Converts an integer to a pointer. To convert the other way, use @ptrToInt. + Converts an integer to a pointer. To convert the other way, use {#link|@ptrToInt#}.

{#header_close#} {#header_open|@IntType#} @@ -4286,7 +4290,7 @@ test "call foo" {
  • fn()
  • ?fn()
    • -

    To convert the other way, use @intToPtr

    +

    To convert the other way, use {#link|@intToPtr#}

    {#header_close#} {#header_open|@rem#} @@ -4539,9 +4543,9 @@ pub const TypeId = enum { Zig has three build modes:

    To add standard build options to a build.zig file: @@ -4592,7 +4596,7 @@ pub fn build(b: &Builder) -> %void { detected at compile-time, Zig emits an error. Most undefined behavior that cannot be detected at compile-time can be detected at runtime. In these cases, Zig has safety checks. Safety checks can be disabled on a per-block basis - with @setDebugSafety. The ReleaseFast + with @setDebugSafety. The {#link|ReleaseFast#} build mode disables all safety checks in order to facilitate optimizations.