| ... | @@ -388,22 +388,15 @@ | ... | @@ -388,22 +388,15 @@ |
| 388 | </p> | 388 | </p> |
| 389 | {#see_also|Values|Tuples|@import|Errors|Entry Point|Source Encoding|try#} | 389 | {#see_also|Values|Tuples|@import|Errors|Entry Point|Source Encoding|try#} |
| 390 | {#header_close#} | 390 | {#header_close#} |
| | 391 | |
| 391 | {#header_open|Comments#} | 392 | {#header_open|Comments#} |
| 392 | <p> | 393 | <p>There are three types of comments. Normal comments are ignored, while {#link|Doc Comments#} |
| 393 | Zig supports 3 types of comments. Normal comments are ignored, but doc comments | 394 | and {#link|Top-Level Doc Comments#} are used by the compiler to generate |
| 394 | and top-level doc comments are used by the compiler to generate the package documentation. | 395 | the package documentation.</p> |
| 395 | </p> | | |
| 396 | <p> | | |
| 397 | The generated documentation is still experimental, and can be produced with: | | |
| 398 | </p> | | |
| 399 | {#shell_samp#}zig test -femit-docs main.zig{#end_shell_samp#} | | |
| 400 | {#code|comments.zig#} | 396 | {#code|comments.zig#} |
| 401 | | 397 | |
| 402 | <p> | 398 | <p>There are no multiline comments. Zig has the property that each line |
| 403 | There are no multiline comments in Zig (e.g. like <code class="c">/* */</code> | 399 | of code can be tokenized independently.</p> |
| 404 | comments in C). This allows Zig to have the property that each line | | |
| 405 | of code can be tokenized out of context. | | |
| 406 | </p> | | |
| 407 | {#header_open|Doc Comments#} | 400 | {#header_open|Doc Comments#} |
| 408 | <p> | 401 | <p> |
| 409 | A doc comment is one that begins with exactly three slashes (i.e. | 402 | A doc comment is one that begins with exactly three slashes (i.e. |
| ... | @@ -429,17 +422,28 @@ | ... | @@ -429,17 +422,28 @@ |
| 429 | {#header_open|Top-Level Doc Comments#} | 422 | {#header_open|Top-Level Doc Comments#} |
| 430 | <p> | 423 | <p> |
| 431 | A top-level doc comment is one that begins with two slashes and an exclamation | 424 | A top-level doc comment is one that begins with two slashes and an exclamation |
| 432 | point: {#syntax#}//!{#endsyntax#}; it documents the current source file. | 425 | point: {#syntax#}//!{#endsyntax#}; it documents the type which owns the containing |
| | 426 | {#link|Namespace#}. |
| 433 | </p> | 427 | </p> |
| 434 | <p> | 428 | <p> |
| 435 | It is a compile error if a top-level doc comment is not placed at the start | 429 | It is a compile error if a top-level doc comment is not placed at the start |
| 436 | of a {#link|container|Containers#}, before any expressions. | 430 | of a namespace, before any expressions. |
| 437 | </p> | 431 | </p> |
| 438 | {#code|tldoc_comments.zig#} | 432 | {#code|tldoc_comments.zig#} |
| 439 | | 433 | |
| 440 | {#header_close#} | 434 | {#header_close#} |
| 441 | {#header_close#} | 435 | {#header_close#} |
| 442 | | 436 | |
| | 437 | {#header_open|Namespace#} |
| | 438 | <p>A namespace in Zig is created by {#link|struct#}, {#link|enum#}, {#link|union#}, and {#link|opaque#}.</p> |
| | 439 | <p>They contain {#link|Namespace Level Variables#}, |
| | 440 | {#link|function|Functions#} declarations, and {#link|comptime#} blocks.</p> |
| | 441 | <p>Although namespaces use curly braces to surround their definition, |
| | 442 | they should not be confused with {#link|blocks|Blocks#} or function bodies.</p> |
| | 443 | <p><strong>Every Zig source file is implicitly a struct</strong>, with the keyword |
| | 444 | {#syntax#}struct{#endsyntax#} and curly braces omitted.</p> |
| | 445 | {#header_close#} |
| | 446 | |
| 443 | {#header_open|Identifiers#} | 447 | {#header_open|Identifiers#} |
| 444 | <p> | 448 | <p> |
| 445 | Identifiers must start with an alphabetic character or underscore and may be followed | 449 | Identifiers must start with an alphabetic character or underscore and may be followed |
| ... | @@ -813,7 +817,7 @@ | ... | @@ -813,7 +817,7 @@ |
| 813 | {#code|destructuring_to_existing.zig#} | 817 | {#code|destructuring_to_existing.zig#} |
| 814 | | 818 | |
| 815 | <p> | 819 | <p> |
| 816 | A destructuring expression may only appear within a block (i.e. not at container scope). | 820 | A destructuring expression may only appear within a block (i.e. not at {#link|Namespace#} scope). |
| 817 | The left hand side of the assignment must consist of a comma separated list, | 821 | The left hand side of the assignment must consist of a comma separated list, |
| 818 | each element of which may be either an lvalue (for instance, an existing `var`) or a variable declaration: | 822 | each element of which may be either an lvalue (for instance, an existing `var`) or a variable declaration: |
| 819 | </p> | 823 | </p> |
| ... | @@ -993,27 +997,23 @@ | ... | @@ -993,27 +997,23 @@ |
| 993 | </p> | 997 | </p> |
| 994 | {#see_also|Exporting a C Library#} | 998 | {#see_also|Exporting a C Library#} |
| 995 | | 999 | |
| 996 | {#header_open|Container Level Variables#} | 1000 | {#header_open|Namespace Level Variables#} |
| 997 | <p> | 1001 | <p>{#link|Namespace|Namespace#} level variables have global lifetime and are |
| 998 | {#link|Container|Containers#} level variables have static lifetime and are order-independent and lazily analyzed. | 1002 | order-independent and lazily analyzed. The initialization value of |
| 999 | The initialization value of container level variables is implicitly | 1003 | namespace level variables is implicitly {#link|comptime#}. If a namespace |
| 1000 | {#link|comptime#}. If a container level variable is {#syntax#}const{#endsyntax#} then its value is | 1004 | level variable is {#syntax#}const{#endsyntax#} then its value is |
| 1001 | {#syntax#}comptime{#endsyntax#}-known, otherwise it is runtime-known. | 1005 | {#syntax#}comptime{#endsyntax#}-known, otherwise it is runtime-known.</p> |
| 1002 | </p> | 1006 | {#code|test_namespace_level_variables.zig#} |
| 1003 | {#code|test_container_level_variables.zig#} | 1007 | <p>Namespace level variables may be declared inside a {#link|struct#}, |
| 1004 | | 1008 | {#link|union#}, {#link|enum#}, or {#link|opaque#}:</p> |
| 1005 | <p> | 1009 | {#code|test_namespaced_variable.zig#} |
| 1006 | Container level variables may be declared inside a {#link|struct#}, {#link|union#}, {#link|enum#}, or {#link|opaque#}: | | |
| 1007 | </p> | | |
| 1008 | {#code|test_namespaced_container_level_variable.zig#} | | |
| 1009 | | 1010 | |
| 1010 | {#header_close#} | 1011 | {#header_close#} |
| 1011 | | 1012 | |
| 1012 | {#header_open|Static Local Variables#} | 1013 | {#header_open|Locally-Scoped Global Variables#} |
| 1013 | <p> | 1014 | <p>It is also possible to have local variables with global lifetime by |
| 1014 | It is also possible to have local variables with static lifetime by using containers inside functions. | 1015 | using {#link|namespaces|Namespace#} inside functions.</p> |
| 1015 | </p> | 1016 | {#code|test_locally_scoped_global_variable.zig#} |
| 1016 | {#code|test_static_local_variable.zig#} | | |
| 1017 | | 1017 | |
| 1018 | {#header_close#} | 1018 | {#header_close#} |
| 1019 | | 1019 | |
| ... | @@ -1022,10 +1022,8 @@ | ... | @@ -1022,10 +1022,8 @@ |
| 1022 | {#syntax#}threadlocal{#endsyntax#} keyword, | 1022 | {#syntax#}threadlocal{#endsyntax#} keyword, |
| 1023 | which makes each thread work with a separate instance of the variable:</p> | 1023 | which makes each thread work with a separate instance of the variable:</p> |
| 1024 | {#code|test_thread_local_variables.zig#} | 1024 | {#code|test_thread_local_variables.zig#} |
| 1025 | | 1025 | <p>For {#link|Single Threaded Builds#}, all thread local variables are |
| 1026 | <p> | 1026 | treated as regular {#link|Namespace Level Variables#}.</p> |
| 1027 | For {#link|Single Threaded Builds#}, all thread local variables are treated as regular {#link|Container Level Variables#}. | | |
| 1028 | </p> | | |
| 1029 | <p> | 1027 | <p> |
| 1030 | Thread local variables may not be {#syntax#}const{#endsyntax#}. | 1028 | Thread local variables may not be {#syntax#}const{#endsyntax#}. |
| 1031 | </p> | 1029 | </p> |
| ... | @@ -4124,13 +4122,11 @@ fn performFn(start_value: i32) i32 { | ... | @@ -4124,13 +4122,11 @@ fn performFn(start_value: i32) i32 { |
| 4124 | </p> | 4122 | </p> |
| 4125 | {#code|test_fibonacci_comptime_unreachable.zig#} | 4123 | {#code|test_fibonacci_comptime_unreachable.zig#} |
| 4126 | | 4124 | |
| 4127 | | 4125 | <p>At {#link|Namespace#} level (outside of any function), all expressions |
| 4128 | <p> | 4126 | are implicitly {#syntax#}comptime{#endsyntax#} expressions. This means |
| 4129 | At {#link|container|Containers#} level (outside of any function), all expressions are implicitly | 4127 | that we can use functions to initialize complex constant data. For |
| 4130 | {#syntax#}comptime{#endsyntax#} expressions. This means that we can use functions to | 4128 | example:</p> |
| 4131 | initialize complex static data. For example: | 4129 | {#code|test_namespace-level_comptime_expressions.zig#} |
| 4132 | </p> | | |
| 4133 | {#code|test_container-level_comptime_expressions.zig#} | | |
| 4134 | | 4130 | |
| 4135 | <p> | 4131 | <p> |
| 4136 | When we compile this program, Zig generates the constants | 4132 | When we compile this program, Zig generates the constants |
| ... | @@ -4310,7 +4306,7 @@ pub fn print(self: *Writer, arg0: []const u8, arg1: i32) !void { | ... | @@ -4310,7 +4306,7 @@ pub fn print(self: *Writer, arg0: []const u8, arg1: i32) !void { |
| 4310 | | 4306 | |
| 4311 | {#header_open|Global Assembly#} | 4307 | {#header_open|Global Assembly#} |
| 4312 | <p> | 4308 | <p> |
| 4313 | When an assembly expression occurs in a {#link|container|Containers#} level {#link|comptime#} block, this is | 4309 | When an assembly expression occurs in a {#link|Namespace#} level {#link|comptime#} block, this is |
| 4314 | <strong>global assembly</strong>. | 4310 | <strong>global assembly</strong>. |
| 4315 | </p> | 4311 | </p> |
| 4316 | <p> | 4312 | <p> |
| ... | @@ -5015,25 +5011,18 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val | ... | @@ -5015,25 +5011,18 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val |
| 5015 | {#header_close#} | 5011 | {#header_close#} |
| 5016 | | 5012 | |
| 5017 | {#header_open|@hasDecl#} | 5013 | {#header_open|@hasDecl#} |
| 5018 | <pre>{#syntax#}@hasDecl(comptime Container: type, comptime name: []const u8) bool{#endsyntax#}</pre> | 5014 | <pre>{#syntax#}@hasDecl(comptime Namespace: type, comptime name: []const u8) bool{#endsyntax#}</pre> |
| 5019 | <p> | 5015 | <p>Returns whether or not a {#link|Namespace#} has a declaration matching {#syntax#}name{#endsyntax#}.</p> |
| 5020 | Returns whether or not a {#link|container|Containers#} has a declaration | | |
| 5021 | matching {#syntax#}name{#endsyntax#}. | | |
| 5022 | </p> | | |
| 5023 | {#code|test_hasDecl_builtin.zig#} | 5016 | {#code|test_hasDecl_builtin.zig#} |
| 5024 | | 5017 | |
| 5025 | {#see_also|@hasField#} | 5018 | {#see_also|@hasField#} |
| 5026 | {#header_close#} | 5019 | {#header_close#} |
| 5027 | | 5020 | |
| 5028 | {#header_open|@hasField#} | 5021 | {#header_open|@hasField#} |
| 5029 | <pre>{#syntax#}@hasField(comptime Container: type, comptime name: []const u8) bool{#endsyntax#}</pre> | 5022 | <pre>{#syntax#}@hasField(comptime T: type, comptime name: []const u8) bool{#endsyntax#}</pre> |
| 5030 | <p>Returns whether the field name of a struct, union, or enum exists.</p> | 5023 | <p>Returns whether the field name of a struct, union, or enum exists.</p> |
| 5031 | <p> | 5024 | <p>The result is a compile time constant.</p> |
| 5032 | The result is a compile time constant. | 5025 | <p>It does not include functions, variables, or constants.</p> |
| 5033 | </p> | | |
| 5034 | <p> | | |
| 5035 | It does not include functions, variables, or constants. | | |
| 5036 | </p> | | |
| 5037 | {#see_also|@hasDecl#} | 5026 | {#see_also|@hasDecl#} |
| 5038 | {#header_close#} | 5027 | {#header_close#} |
| 5039 | | 5028 | |
| ... | @@ -6049,7 +6038,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val | ... | @@ -6049,7 +6038,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val |
| 6049 | {#header_open|Single Threaded Builds#} | 6038 | {#header_open|Single Threaded Builds#} |
| 6050 | <p>Zig has a compile option <kbd>-fsingle-threaded</kbd> which has the following effects:</p> | 6039 | <p>Zig has a compile option <kbd>-fsingle-threaded</kbd> which has the following effects:</p> |
| 6051 | <ul> | 6040 | <ul> |
| 6052 | <li>All {#link|Thread Local Variables#} are treated as regular {#link|Container Level Variables#}.</li> | 6041 | <li>All {#link|Thread Local Variables#} are treated as regular {#link|Namespace Level Variables#}.</li> |
| 6053 | <li>The overhead of {#link|Async Functions#} becomes equivalent to function call overhead.</li> | 6042 | <li>The overhead of {#link|Async Functions#} becomes equivalent to function call overhead.</li> |
| 6054 | <li>The {#syntax#}@import("builtin").single_threaded{#endsyntax#} becomes {#syntax#}true{#endsyntax#} | 6043 | <li>The {#syntax#}@import("builtin").single_threaded{#endsyntax#} becomes {#syntax#}true{#endsyntax#} |
| 6055 | and therefore various userland APIs which read this variable become more efficient. | 6044 | and therefore various userland APIs which read this variable become more efficient. |
| ... | @@ -6704,7 +6693,7 @@ const builtin = @import("builtin"); | ... | @@ -6704,7 +6693,7 @@ const builtin = @import("builtin"); |
| 6704 | {#header_open|Panic Handler#} | 6693 | {#header_open|Panic Handler#} |
| 6705 | <p> | 6694 | <p> |
| 6706 | The Zig Standard Library looks for a declaration named {#syntax#}panic{#endsyntax#} in the root module's | 6695 | The Zig Standard Library looks for a declaration named {#syntax#}panic{#endsyntax#} in the root module's |
| 6707 | root source file. If present, it is expected to be a namespace (container type) with declarations | 6696 | root source file. If present, it is expected to be a {#link|Namespace#} with declarations |
| 6708 | providing different panic handlers. | 6697 | providing different panic handlers. |
| 6709 | </p> | 6698 | </p> |
| 6710 | <p> | 6699 | <p> |
| ... | @@ -7916,18 +7905,6 @@ fn readU32Be() u32 {} | ... | @@ -7916,18 +7905,6 @@ fn readU32Be() u32 {} |
| 7916 | {#header_close#} | 7905 | {#header_close#} |
| 7917 | | 7906 | |
| 7918 | {#header_open|Appendix#} | 7907 | {#header_open|Appendix#} |
| 7919 | {#header_open|Containers#} | | |
| 7920 | <p> | | |
| 7921 | A <em>container</em> in Zig is any syntactical construct that acts as a namespace to hold {#link|variable|Container Level Variables#} and {#link|function|Functions#} declarations. | | |
| 7922 | Containers are also type definitions which can be instantiated. | | |
| 7923 | {#link|Structs|struct#}, {#link|enums|enum#}, {#link|unions|union#}, {#link|opaques|opaque#}, and even Zig source files themselves are containers. | | |
| 7924 | </p> | | |
| 7925 | <p> | | |
| 7926 | Although containers (except Zig source files) use curly braces to surround their definition, they should not be confused with {#link|blocks|Blocks#} or functions. | | |
| 7927 | Containers do not contain statements. | | |
| 7928 | </p> | | |
| 7929 | {#header_close#} | | |
| 7930 | | | |
| 7931 | {#header_open|Grammar#} | 7908 | {#header_open|Grammar#} |
| 7932 | {#syntax_block|peg|grammar.peg#} | 7909 | {#syntax_block|peg|grammar.peg#} |
| 7933 | Root <- skip ContainerMembers eof | 7910 | Root <- skip ContainerMembers eof |
Andrew Kelley <andrew@ziglang.org> 2026-04-19 10:38:01-07:00
Alex Rønne Petersen <alex@alexrp.com> 2026-04-20 01:59:20+02:00
Signed by SSH key SHA256:7B/LJ7bpR1eX8aCXSr4mtd5M45VMPKcx9zY8e95b5QM
doc