diff --git a/doc/langref.html.in b/doc/langref.html.in index 3486bef867..ac046d4dd8 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -388,22 +388,15 @@

{#see_also|Values|Tuples|@import|Errors|Entry Point|Source Encoding|try#} {#header_close#} + {#header_open|Comments#} -

- 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 source file. + 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#}.

@@ -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: