- Zig supports 3 types of comments. Normal comments are ignored, but doc comments - and top-level doc comments are used by the compiler to generate the package documentation. -
-- The generated documentation is still experimental, and can be produced with: -
- {#shell_samp#}zig test -femit-docs main.zig{#end_shell_samp#} +There are three types of comments. Normal comments are ignored, while {#link|Doc Comments#} + and {#link|Top-Level Doc Comments#} are used by the compiler to generate + the package documentation.
{#code|comments.zig#} -
- There are no multiline comments in Zig (e.g. like /* */
- comments in C). This allows Zig to have the property that each line
- of code can be tokenized out of context.
-
There are no multiline comments. Zig has the property that each line + of code can be tokenized independently.
{#header_open|Doc Comments#}A doc comment is one that begins with exactly three slashes (i.e. @@ -429,17 +422,28 @@ {#header_open|Top-Level Doc Comments#}
A top-level doc comment is one that begins with two slashes and an exclamation - point: {#syntax#}//!{#endsyntax#}; it documents the current module. + point: {#syntax#}//!{#endsyntax#}; it documents the type which owns the containing + {#link|Namespace#}.
It is a compile error if a top-level doc comment is not placed at the start - of a {#link|container|Containers#}, before any expressions. + of a namespace, before any expressions.
{#code|tldoc_comments.zig#} {#header_close#} {#header_close#} + {#header_open|Namespace#} +A namespace in Zig is created by {#link|struct#}, {#link|enum#}, {#link|union#}, and {#link|opaque#}.
+They contain {#link|Namespace Level Variables#}, + {#link|function|Functions#} declarations, and {#link|comptime#} blocks.
+Although namespaces use curly braces to surround their definition, + they should not be confused with {#link|blocks|Blocks#} or function bodies.
+Every Zig source file is implicitly a struct, with the keyword + {#syntax#}struct{#endsyntax#} and curly braces omitted.
+ {#header_close#} + {#header_open|Identifiers#}Identifiers must start with an alphabetic character or underscore and may be followed @@ -813,7 +817,7 @@ {#code|destructuring_to_existing.zig#}
- A destructuring expression may only appear within a block (i.e. not at container scope). + A destructuring expression may only appear within a block (i.e. not at {#link|Namespace#} scope). The left hand side of the assignment must consist of a comma separated list, each element of which may be either an lvalue (for instance, an existing `var`) or a variable declaration:
@@ -993,27 +997,23 @@ {#see_also|Exporting a C Library#} - {#header_open|Container Level Variables#} -- {#link|Container|Containers#} level variables have static lifetime and are order-independent and lazily analyzed. - The initialization value of container level variables is implicitly - {#link|comptime#}. If a container level variable is {#syntax#}const{#endsyntax#} then its value is - {#syntax#}comptime{#endsyntax#}-known, otherwise it is runtime-known. -
- {#code|test_container_level_variables.zig#} - -- Container level variables may be declared inside a {#link|struct#}, {#link|union#}, {#link|enum#}, or {#link|opaque#}: -
- {#code|test_namespaced_container_level_variable.zig#} + {#header_open|Namespace Level Variables#} +{#link|Namespace|Namespace#} level variables have global lifetime and are + order-independent and lazily analyzed. The initialization value of + namespace level variables is implicitly {#link|comptime#}. If a namespace + level variable is {#syntax#}const{#endsyntax#} then its value is + {#syntax#}comptime{#endsyntax#}-known, otherwise it is runtime-known.
+ {#code|test_namespace_level_variables.zig#} +Namespace level variables may be declared inside a {#link|struct#}, + {#link|union#}, {#link|enum#}, or {#link|opaque#}:
+ {#code|test_namespaced_variable.zig#} {#header_close#} - {#header_open|Static Local Variables#} -- It is also possible to have local variables with static lifetime by using containers inside functions. -
- {#code|test_static_local_variable.zig#} + {#header_open|Locally-Scoped Global Variables#} +It is also possible to have local variables with global lifetime by + using {#link|namespaces|Namespace#} inside functions.
+ {#code|test_locally_scoped_global_variable.zig#} {#header_close#} @@ -1022,10 +1022,8 @@ {#syntax#}threadlocal{#endsyntax#} keyword, which makes each thread work with a separate instance of the variable: {#code|test_thread_local_variables.zig#} - -- For {#link|Single Threaded Builds#}, all thread local variables are treated as regular {#link|Container Level Variables#}. -
+For {#link|Single Threaded Builds#}, all thread local variables are + treated as regular {#link|Namespace Level Variables#}.
Thread local variables may not be {#syntax#}const{#endsyntax#}.
@@ -2470,7 +2468,7 @@ orUnions can be declared with an enum tag type. This turns the union into a tagged union, which makes it eligible to use with {#link|switch#} expressions. When switching on tagged unions, - the tag value can be obtained using an additional capture. + the tag value can be obtained using an additional capture. Tagged unions coerce to their tag type: {#link|Type Coercion: Unions and Enums#}.
{#code|test_tagged_union.zig#} @@ -4123,13 +4121,11 @@ fn performFn(start_value: i32) i32 { {#code|test_fibonacci_comptime_unreachable.zig#} - -- At {#link|container|Containers#} level (outside of any function), all expressions are implicitly - {#syntax#}comptime{#endsyntax#} expressions. This means that we can use functions to - initialize complex static data. For example: -
- {#code|test_container-level_comptime_expressions.zig#} +At {#link|Namespace#} level (outside of any function), all expressions + are implicitly {#syntax#}comptime{#endsyntax#} expressions. This means + that we can use functions to initialize complex constant data. For + example:
+ {#code|test_namespace-level_comptime_expressions.zig#}When we compile this program, Zig generates the constants @@ -4309,7 +4305,7 @@ pub fn print(self: *Writer, arg0: []const u8, arg1: i32) !void { {#header_open|Global Assembly#}
- When an assembly expression occurs in a {#link|container|Containers#} level {#link|comptime#} block, this is + When an assembly expression occurs in a {#link|Namespace#} level {#link|comptime#} block, this is global assembly.
@@ -4946,25 +4942,18 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val {#header_close#} {#header_open|@hasDecl#} -
{#syntax#}@hasDecl(comptime Container: type, comptime name: []const u8) bool{#endsyntax#}
- - Returns whether or not a {#link|container|Containers#} has a declaration - matching {#syntax#}name{#endsyntax#}. -
+{#syntax#}@hasDecl(comptime Namespace: type, comptime name: []const u8) bool{#endsyntax#}
+ Returns whether or not a {#link|Namespace#} has a declaration matching {#syntax#}name{#endsyntax#}.
{#code|test_hasDecl_builtin.zig#} {#see_also|@hasField#} {#header_close#} {#header_open|@hasField#} -{#syntax#}@hasField(comptime Container: type, comptime name: []const u8) bool{#endsyntax#}
+ {#syntax#}@hasField(comptime T: type, comptime name: []const u8) bool{#endsyntax#}
Returns whether the field name of a struct, union, or enum exists.
-- The result is a compile time constant. -
-- It does not include functions, variables, or constants. -
+The result is a compile time constant.
+It does not include functions, variables, or constants.
{#see_also|@hasDecl#} {#header_close#} @@ -5980,7 +5969,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val {#header_open|Single Threaded Builds#}Zig has a compile option -fsingle-threaded which has the following effects:
The Zig Standard Library looks for a declaration named {#syntax#}panic{#endsyntax#} in the root module's - root source file. If present, it is expected to be a namespace (container type) with declarations + root source file. If present, it is expected to be a {#link|Namespace#} with declarations providing different panic handlers.
@@ -7755,18 +7744,6 @@ fn readU32Be() u32 {} {#header_close#} {#header_open|Appendix#} - {#header_open|Containers#} -
- A container in Zig is any syntactical construct that acts as a namespace to hold {#link|variable|Container Level Variables#} and {#link|function|Functions#} declarations. - Containers are also type definitions which can be instantiated. - {#link|Structs|struct#}, {#link|enums|enum#}, {#link|unions|union#}, {#link|opaques|opaque#}, and even Zig source files themselves are containers. -
-- Although containers (except Zig source files) use curly braces to surround their definition, they should not be confused with {#link|blocks|Blocks#} or functions. - Containers do not contain statements. -
- {#header_close#} - {#header_open|Grammar#} {#syntax_block|peg|grammar.peg#} Root <- skip ContainerMembers eof diff --git a/doc/langref/test_container-level_comptime_expressions.zig b/doc/langref/test_container-level_comptime_expressions.zig deleted file mode 100644 index 78d5cb4cbbcf8e8daba22ef493d2dc231d0e4d23..0000000000000000000000000000000000000000 --- a/doc/langref/test_container-level_comptime_expressions.zig +++ /dev/null @@ -1,37 +0,0 @@ -const first_25_primes = firstNPrimes(25); -const sum_of_first_25_primes = sum(&first_25_primes); - -fn firstNPrimes(comptime n: usize) [n]i32 { - var prime_list: [n]i32 = undefined; - var next_index: usize = 0; - var test_number: i32 = 2; - while (next_index < prime_list.len) : (test_number += 1) { - var test_prime_index: usize = 0; - var is_prime = true; - while (test_prime_index < next_index) : (test_prime_index += 1) { - if (test_number % prime_list[test_prime_index] == 0) { - is_prime = false; - break; - } - } - if (is_prime) { - prime_list[next_index] = test_number; - next_index += 1; - } - } - return prime_list; -} - -fn sum(numbers: []const i32) i32 { - var result: i32 = 0; - for (numbers) |x| { - result += x; - } - return result; -} - -test "variable values" { - try @import("std").testing.expectEqual(1060, sum_of_first_25_primes); -} - -// test diff --git a/doc/langref/test_container_level_variables.zig b/doc/langref/test_container_level_variables.zig deleted file mode 100644 index 372fda1863f95659c313149052b65d2b7dfc0a6c..0000000000000000000000000000000000000000 --- a/doc/langref/test_container_level_variables.zig +++ /dev/null @@ -1,16 +0,0 @@ -var y: i32 = add(10, x); -const x: i32 = add(12, 34); - -test "container level variables" { - try expectEqual(46, x); - try expectEqual(56, y); -} - -fn add(a: i32, b: i32) i32 { - return a + b; -} - -const std = @import("std"); -const expectEqual = std.testing.expectEqual; - -// test diff --git a/doc/langref/test_locally_scoped_global_variable.zig b/doc/langref/test_locally_scoped_global_variable.zig new file mode 100644 index 0000000000000000000000000000000000000000..58b4505be49cda320397633ed5a0de0b29934f17 --- /dev/null +++ b/doc/langref/test_locally_scoped_global_variable.zig @@ -0,0 +1,17 @@ +const std = @import("std"); +const expectEqual = std.testing.expectEqual; + +test "static local variable" { + try expectEqual(1235, foo()); + try expectEqual(1236, foo()); +} + +fn foo() i32 { + const S = struct { + var x: i32 = 1234; + }; + S.x += 1; + return S.x; +} + +// test diff --git a/doc/langref/test_namespace-level_comptime_expressions.zig b/doc/langref/test_namespace-level_comptime_expressions.zig new file mode 100644 index 0000000000000000000000000000000000000000..78d5cb4cbbcf8e8daba22ef493d2dc231d0e4d23 --- /dev/null +++ b/doc/langref/test_namespace-level_comptime_expressions.zig @@ -0,0 +1,37 @@ +const first_25_primes = firstNPrimes(25); +const sum_of_first_25_primes = sum(&first_25_primes); + +fn firstNPrimes(comptime n: usize) [n]i32 { + var prime_list: [n]i32 = undefined; + var next_index: usize = 0; + var test_number: i32 = 2; + while (next_index < prime_list.len) : (test_number += 1) { + var test_prime_index: usize = 0; + var is_prime = true; + while (test_prime_index < next_index) : (test_prime_index += 1) { + if (test_number % prime_list[test_prime_index] == 0) { + is_prime = false; + break; + } + } + if (is_prime) { + prime_list[next_index] = test_number; + next_index += 1; + } + } + return prime_list; +} + +fn sum(numbers: []const i32) i32 { + var result: i32 = 0; + for (numbers) |x| { + result += x; + } + return result; +} + +test "variable values" { + try @import("std").testing.expectEqual(1060, sum_of_first_25_primes); +} + +// test diff --git a/doc/langref/test_namespace_level_variables.zig b/doc/langref/test_namespace_level_variables.zig new file mode 100644 index 0000000000000000000000000000000000000000..372fda1863f95659c313149052b65d2b7dfc0a6c --- /dev/null +++ b/doc/langref/test_namespace_level_variables.zig @@ -0,0 +1,16 @@ +var y: i32 = add(10, x); +const x: i32 = add(12, 34); + +test "container level variables" { + try expectEqual(46, x); + try expectEqual(56, y); +} + +fn add(a: i32, b: i32) i32 { + return a + b; +} + +const std = @import("std"); +const expectEqual = std.testing.expectEqual; + +// test diff --git a/doc/langref/test_namespaced_container_level_variable.zig b/doc/langref/test_namespaced_container_level_variable.zig deleted file mode 100644 index f35aa90d8ec7fcc5f3b5ae35995772bb0b713e09..0000000000000000000000000000000000000000 --- a/doc/langref/test_namespaced_container_level_variable.zig +++ /dev/null @@ -1,18 +0,0 @@ -const std = @import("std"); -const expectEqual = std.testing.expectEqual; - -test "namespaced container level variable" { - try expectEqual(1235, foo()); - try expectEqual(1236, foo()); -} - -const S = struct { - var x: i32 = 1234; -}; - -fn foo() i32 { - S.x += 1; - return S.x; -} - -// test diff --git a/doc/langref/test_namespaced_variable.zig b/doc/langref/test_namespaced_variable.zig new file mode 100644 index 0000000000000000000000000000000000000000..f35aa90d8ec7fcc5f3b5ae35995772bb0b713e09 --- /dev/null +++ b/doc/langref/test_namespaced_variable.zig @@ -0,0 +1,18 @@ +const std = @import("std"); +const expectEqual = std.testing.expectEqual; + +test "namespaced container level variable" { + try expectEqual(1235, foo()); + try expectEqual(1236, foo()); +} + +const S = struct { + var x: i32 = 1234; +}; + +fn foo() i32 { + S.x += 1; + return S.x; +} + +// test diff --git a/doc/langref/test_static_local_variable.zig b/doc/langref/test_static_local_variable.zig deleted file mode 100644 index 58b4505be49cda320397633ed5a0de0b29934f17..0000000000000000000000000000000000000000 --- a/doc/langref/test_static_local_variable.zig +++ /dev/null @@ -1,17 +0,0 @@ -const std = @import("std"); -const expectEqual = std.testing.expectEqual; - -test "static local variable" { - try expectEqual(1235, foo()); - try expectEqual(1236, foo()); -} - -fn foo() i32 { - const S = struct { - var x: i32 = 1234; - }; - S.x += 1; - return S.x; -} - -// test diff --git a/doc/langref/tldoc_comments.zig b/doc/langref/tldoc_comments.zig index 6605aac76a057963e799548d70f48c182fed45e1..222ba9342d23904680a1583b779f37568cec9f79 100644 --- a/doc/langref/tldoc_comments.zig +++ b/doc/langref/tldoc_comments.zig @@ -1,11 +1,10 @@ -//! This module provides functions for retrieving the current date and -//! time with varying degrees of precision and accuracy. It does not -//! depend on libc, but will use functions from it if available. +//! Provides functions for retrieving the current date and time with varying +//! degrees of precision and accuracy. const S = struct { - //! Top level comments are allowed inside a container other than a module, - //! but it is not very useful. Currently, when producing the package - //! documentation, these comments are ignored. + //! Top level comments are allowed inside namespaces other than the + //! implicit struct created by files, but it is not very useful. Currently, + //! when producing the package documentation, these comments are ignored. }; // syntax