langref improvements

doc/langref/TopLevelFields.zig

@@ -0,0 +1,18 @@
+//! Because this file contains fields, it is a type which is intended to be instantiated, and so
+//! is named in TitleCase instead of snake_case by convention.
+
+foo: u32,
+bar: u64,
+
+/// `@This()` can be used to refer to this struct type. In files with fields, is quite common to name the type
+/// here, so it can be easily referenced by other declarations.
+const TopLevelFields = @This();
+
+pub fn init(val: u32) TopLevelFields {
+    return .{
+        .foo = val,
+        .bar = val * 10,
+    };
+}
+
+// syntax

doc/langref/entry_point.zig

@@ -0,0 +1,20 @@
+/// `std.start` imports this file using `@import("root")`, and uses this declaration as the program's
+/// user-provided entry point. It can return any of the following types:
+/// * `void`
+/// * `E!void`, for any error set `E`
+/// * `u8`
+/// * `E!u8`, for any error set `E`
+/// Returning a `void` value from this function will exit with code 0.
+/// Returning a `u8` value from this function with exit with the given status code.
+/// Returning an error value from this function will print an Error Return Trace and exit with code 1.
+pub fn main() void {
+    std.debug.print("Hello, World!\n", .{});
+}
+
+// If uncommented, this declaration would suppress the usual std.start logic, causing
+// the `main` declaration above to be ignored.
+//pub const _start = {};
+
+const std = @import("std");
+
+// exe=succeed

doc/langref/libc_export_entry_point.zig

@@ -0,0 +1,10 @@
+pub export fn main(argc: c_int, argv: [*]const [*:0]const u8) c_int {
+    const args = argv[0..@intCast(argc)];
+    std.debug.print("Hello! argv[0] is '{s}'\n", .{args[0]});
+    return 0;
+}
+
+const std = @import("std");
+
+// exe=succeed
+// link_libc

doc/langref/panic_handler.zig

@@ -0,0 +1,18 @@
+pub fn main() void {
+    @setRuntimeSafety(true);
+    var x: u8 = 255;
+    // Let's overflow this integer!
+    x += 1;
+}
+
+pub const panic = std.debug.FullPanic(myPanic);
+
+fn myPanic(msg: []const u8, first_trace_addr: ?usize) noreturn {
+    _ = first_trace_addr;
+    std.debug.print("Panic! {s}\n", .{msg});
+    std.process.exit(1);
+}
+
+const std = @import("std");
+
+// exe=fail

doc/langref/std_options.zig

@@ -0,0 +1,25 @@
+/// The presence of this declaration allows the program to override certain behaviors of the standard library.
+/// For a full list of available options, see the documentation for `std.Options`.
+pub const std_options: std.Options = .{
+    // By default, in safe build modes, the standard library will attach a segfault handler to the program to
+    // print a helpful stack trace if a segmentation fault occurs. Here, we can disable this, or even enable
+    // it in unsafe build modes.
+    .enable_segfault_handler = true,
+    // This is the logging function used by `std.log`.
+    .logFn = myLogFn,
+};
+
+fn myLogFn(
+    comptime level: std.log.Level,
+    comptime scope: @Type(.enum_literal),
+    comptime format: []const u8,
+    args: anytype,
+) void {
+    // We could do anything we want here!
+    // ...but actually, let's just call the default implementation.
+    std.log.defaultLog(level, scope, format, args);
+}
+
+const std = @import("std");
+
+// syntax

doc/langref/test_setRuntimeSafety_builtin.zig

@@ -2,7 +2,7 @@ test "@setRuntimeSafety" {
     // The builtin applies to the scope that it is called in. So here, integer overflow
     // will not be caught in ReleaseFast and ReleaseSmall modes:
     // var x: u8 = 255;
-    // x += 1; // undefined behavior in ReleaseFast/ReleaseSmall modes.
+    // x += 1; // Unchecked Illegal Behavior in ReleaseFast/ReleaseSmall modes.
     {
         // However this block has safety enabled, so safety checks happen here,
         // even in ReleaseFast and ReleaseSmall modes.
@@ -15,7 +15,7 @@ test "@setRuntimeSafety" {
             // would not be caught in any build mode.
             @setRuntimeSafety(false);
             // var x: u8 = 255;
-            // x += 1; // undefined behavior in all build modes.
+            // x += 1; // Unchecked Illegal Behavior in all build modes.
         }
     }
 }