authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2019-09-24 21:23:12-04:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2019-09-24 21:23:12-04:00
log993d5bc9c945a40815b4c9f119f67917961e6c9f
tree6539f647d7ff3f4ae1b9a9bf40046bd523e027e3
parent53210b2304990e9b3b0f35f847e13d4ea4ae4ced
signaturelock-open Commit is signed but in an unrecognized format.

add docs for usingnamespace

closes #1589

1 files changed, 35 insertions(+), 0 deletions(-)

doc/langref.html.in+35
...@@ -5187,6 +5187,41 @@ test "@intToPtr for pointer to zero bit type" {...@@ -5187,6 +5187,41 @@ test "@intToPtr for pointer to zero bit type" {
5187 </p>5187 </p>
5188 {#header_close#}5188 {#header_close#}
51895189
5190 {#header_open|usingnamespace#}
5191 <p>
5192 {#syntax#}usingnamespace{#endsyntax#} is a top level declaration that imports all the declarations of
5193 the operand, which must be a {#link|struct#}, {#link|union#}, or {#link|enum#}, into the current scope:
5194 </p>
5195 {#code_begin|test|usingnamespace#}
5196usingnamespace @import("std");
5197
5198test "using std namespace" {
5199 debug.assert(true);
5200}
5201 {#code_end#}
5202 <p>
5203 Instead of the above pattern, it is generally recommended to explicitly alias individual declarations.
5204 However, {#syntax#}usingnamespace{#endsyntax#} has an important use case when organizing the public
5205 API of a file or package. For example, one might have <code>c.zig</code> with all of the
5206 {#link|C imports|Import from C Header File#}:
5207 </p>
5208 <pre>{#syntax#}
5209pub usingnamespace @cImport({
5210 @cInclude("epoxy/gl.h");
5211 @cInclude("GLFW/glfw3.h");
5212 @cDefine("STBI_ONLY_PNG", "");
5213 @cDefine("STBI_NO_STDIO", "");
5214 @cInclude("stb_image.h");
5215});
5216 {#endsyntax#}</pre>
5217 <p>
5218 The above example demonstrates using {#syntax#}pub{#endsyntax#} to qualify the
5219 {#syntax#}usingnamespace{#endsyntax#} additionally makes the imported declarations
5220 {#syntax#}pub{#endsyntax#}. This can be used to forward declarations, giving precise control
5221 over what declarations a given file exposes.
5222 </p>
5223 {#header_close#}
5224
5190 {#header_open|comptime#}5225 {#header_open|comptime#}
5191 <p>5226 <p>
5192 Zig places importance on the concept of whether an expression is known at compile-time.5227 Zig places importance on the concept of whether an expression is known at compile-time.