authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2019-03-13 13:04:55-04:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2019-03-13 13:05:23-04:00
log0588fed15f64cc7d53eff2c599beb63ae2a589a0
tree00d4620dd23acc0799ad3cd7d03c04996ce9d1e0
parentd495dcc3c952c99e5358d9610cf09eb856f643b0
signaturelock-open Commit is signed but in an unrecognized format.

add documentation for `pub`

closes #1727

1 files changed, 139 insertions(+), 49 deletions(-)

doc/langref.html.in+139-49
...@@ -5890,10 +5890,11 @@ comptime {...@@ -5890,10 +5890,11 @@ comptime {
5890 {#see_also|Import from C Header File|@cInclude|@cImport|@cUndef|void#}5890 {#see_also|Import from C Header File|@cInclude|@cImport|@cUndef|void#}
5891 {#header_close#}5891 {#header_close#}
5892 {#header_open|@cImport#}5892 {#header_open|@cImport#}
5893 <pre>{#syntax#}@cImport(expression) (namespace){#endsyntax#}</pre>5893 <pre>{#syntax#}@cImport(expression) type{#endsyntax#}</pre>
5894 <p>5894 <p>
5895 This function parses C code and imports the functions, types, variables, and5895 This function parses C code and imports the functions, types, variables,
5896 compatible macro definitions into the result namespace.5896 and compatible macro definitions into a new empty struct type, and then
5897 returns that type.
5897 </p>5898 </p>
5898 <p>5899 <p>
5899 {#syntax#}expression{#endsyntax#} is interpreted at compile time. The builtin functions5900 {#syntax#}expression{#endsyntax#} is interpreted at compile time. The builtin functions
...@@ -6320,14 +6321,22 @@ export fn @"A function name that is a complete sentence."() void {}...@@ -6320,14 +6321,22 @@ export fn @"A function name that is a complete sentence."() void {}
6320 {#header_close#}6321 {#header_close#}
63216322
6322 {#header_open|@import#}6323 {#header_open|@import#}
6323 <pre>{#syntax#}@import(comptime path: []u8) (namespace){#endsyntax#}</pre>6324 <pre>{#syntax#}@import(comptime path: []u8) type{#endsyntax#}</pre>
6324 <p>6325 <p>
6325 This function finds a zig file corresponding to {#syntax#}path{#endsyntax#} and imports all the6326 This function finds a zig file corresponding to {#syntax#}path{#endsyntax#} and adds it to the build,
6326 public top level declarations into the resulting namespace.6327 if it is not already added.
6328 </p>
6329 <p>
6330 Zig source files are implicitly structs, with a name equal to the file's basename with the extension
6331 truncated. {#syntax#}@import{#endsyntax#} returns the struct type corresponding to the file.
6332 </p>
6333 <p>
6334 Declarations which have the {#syntax#}pub{#endsyntax#} keyword may be referenced from a different
6335 source file than the one they are declared in.
6327 </p>6336 </p>
6328 <p>6337 <p>
6329 {#syntax#}path{#endsyntax#} can be a relative or absolute path, or it can be the name of a package.6338 {#syntax#}path{#endsyntax#} can be a relative or absolute path, or it can be the name of a package.
6330 If it is a relative path, it is relative to the file that contains the {#syntax#}@import{#endsyntax#}6339 If it is a relative path, it is relative to the file that contains the {#syntax#}@import{#endsyntax#}
6331 function call.6340 function call.
6332 </p>6341 </p>
6333 <p>6342 <p>
...@@ -6335,7 +6344,9 @@ export fn @"A function name that is a complete sentence."() void {}...@@ -6335,7 +6344,9 @@ export fn @"A function name that is a complete sentence."() void {}
6335 </p>6344 </p>
6336 <ul>6345 <ul>
6337 <li>{#syntax#}@import("std"){#endsyntax#} - Zig Standard Library</li>6346 <li>{#syntax#}@import("std"){#endsyntax#} - Zig Standard Library</li>
6338 <li>{#syntax#}@import("builtin"){#endsyntax#} - Compiler-provided types and variables</li>6347 <li>{#syntax#}@import("builtin"){#endsyntax#} - Compiler-provided types and variables.
6348 The command <code>zig builtin</code> outputs the source to stdout for reference.
6349 </li>
6339 </ul>6350 </ul>
6340 {#see_also|Compile Variables|@embedFile#}6351 {#see_also|Compile Variables|@embedFile#}
6341 {#header_close#}6352 {#header_close#}
...@@ -8177,28 +8188,68 @@ all your base are belong to us</code></pre>...@@ -8177,28 +8188,68 @@ all your base are belong to us</code></pre>
8177 </p>8188 </p>
8178 <pre><code class="shell">$ zig targets8189 <pre><code class="shell">$ zig targets
8179Architectures:8190Architectures:
8180 armv8_2a8191 arm
8181 armv8_1a8192 v8_4a
8182 armv88193 v8_3a
8183 armv8r8194 v8_2a
8184 armv8m_baseline8195 v8_1a
8185 armv8m_mainline8196 v8
8186 armv78197 v8r
8187 armv7em8198 v8m_baseline
8188 armv7m8199 v8m_mainline
8189 armv7s8200 v7
8190 armv7k8201 v7em
8191 armv7ve8202 v7m
8192 armv68203 v7s
8193 armv6m8204 v7k
8194 armv6k8205 v7ve
8195 armv6t28206 v6
8196 armv58207 v6m
8197 armv5te8208 v6k
8198 armv4t8209 v6t2
8210 v5
8211 v5te
8212 v4t
8199 armeb8213 armeb
8214 v8_4a
8215 v8_3a
8216 v8_2a
8217 v8_1a
8218 v8
8219 v8r
8220 v8m_baseline
8221 v8m_mainline
8222 v7
8223 v7em
8224 v7m
8225 v7s
8226 v7k
8227 v7ve
8228 v6
8229 v6m
8230 v6k
8231 v6t2
8232 v5
8233 v5te
8234 v4t
8200 aarch648235 aarch64
8236 v8_4a
8237 v8_3a
8238 v8_2a
8239 v8_1a
8240 v8
8241 v8r
8242 v8m_baseline
8243 v8m_mainline
8201 aarch64_be8244 aarch64_be
8245 v8_4a
8246 v8_3a
8247 v8_2a
8248 v8_1a
8249 v8
8250 v8r
8251 v8m_baseline
8252 v8m_mainline
8202 avr8253 avr
8203 bpfel8254 bpfel
8204 bpfeb8255 bpfeb
...@@ -8208,7 +8259,6 @@ Architectures:...@@ -8208,7 +8259,6 @@ Architectures:
8208 mips648259 mips64
8209 mips64el8260 mips64el
8210 msp4308261 msp430
8211 nios2
8212 powerpc8262 powerpc
8213 powerpc648263 powerpc64
8214 powerpc64le8264 powerpc64le
...@@ -8220,32 +8270,58 @@ Architectures:...@@ -8220,32 +8270,58 @@ Architectures:
8220 sparcv98270 sparcv9
8221 sparcel8271 sparcel
8222 s390x8272 s390x
8223 tce
8224 tcele
8225 thumb8273 thumb
8274 v8_4a
8275 v8_3a
8276 v8_2a
8277 v8_1a
8278 v8
8279 v8r
8280 v8m_baseline
8281 v8m_mainline
8282 v7
8283 v7em
8284 v7m
8285 v7s
8286 v7k
8287 v7ve
8288 v6
8289 v6m
8290 v6k
8291 v6t2
8292 v5
8293 v5te
8294 v4t
8226 thumbeb8295 thumbeb
8296 v8_4a
8297 v8_3a
8298 v8_2a
8299 v8_1a
8300 v8
8301 v8r
8302 v8m_baseline
8303 v8m_mainline
8304 v7
8305 v7em
8306 v7m
8307 v7s
8308 v7k
8309 v7ve
8310 v6
8311 v6m
8312 v6k
8313 v6t2
8314 v5
8315 v5te
8316 v4t
8227 i3868317 i386
8228 x86_64 (native)8318 x86_64 (native)
8229 xcore8319 xcore
8230 nvptx8320 nvptx
8231 nvptx648321 nvptx64
8232 le32
8233 le64
8234 amdil
8235 amdil64
8236 hsail
8237 hsail64
8238 spir
8239 spir64
8240 kalimbav3
8241 kalimbav4
8242 kalimbav5
8243 shave
8244 lanai8322 lanai
8245 wasm328323 wasm32
8246 wasm648324 wasm64
8247 renderscript32
8248 renderscript64
82498325
8250Operating Systems:8326Operating Systems:
8251 freestanding8327 freestanding
...@@ -8268,7 +8344,6 @@ Operating Systems:...@@ -8268,7 +8344,6 @@ Operating Systems:
8268 rtems8344 rtems
8269 nacl8345 nacl
8270 cnk8346 cnk
8271 bitrig
8272 aix8347 aix
8273 cuda8348 cuda
8274 nvcl8349 nvcl
...@@ -8279,11 +8354,14 @@ Operating Systems:...@@ -8279,11 +8354,14 @@ Operating Systems:
8279 watchos8354 watchos
8280 mesa3d8355 mesa3d
8281 contiki8356 contiki
8357 amdpal
8282 zen8358 zen
8359 uefi
82838360
8284Environments:8361C ABIs:
8285 unknown8362 none
8286 gnu (native)8363 gnu (native)
8364 gnuabin32
8287 gnuabi648365 gnuabi64
8288 gnueabi8366 gnueabi
8289 gnueabihf8367 gnueabihf
...@@ -8298,9 +8376,8 @@ Environments:...@@ -8298,9 +8376,8 @@ Environments:
8298 msvc8376 msvc
8299 itanium8377 itanium
8300 cygnus8378 cygnus
8301 amdopencl
8302 coreclr8379 coreclr
8303 opencl</code></pre>8380 simulator</code></pre>
8304 <p>8381 <p>
8305 The Zig Standard Library ({#syntax#}@import("std"){#endsyntax#}) has architecture, environment, and operating system8382 The Zig Standard Library ({#syntax#}@import("std"){#endsyntax#}) has architecture, environment, and operating system
8306 abstractions, and thus takes additional work to support more platforms.8383 abstractions, and thus takes additional work to support more platforms.
...@@ -8433,6 +8510,19 @@ fn readU32Be() u32 {}...@@ -8433,6 +8510,19 @@ fn readU32Be() u32 {}
8433 <p>The codepoint U+000a (LF) (which is encoded as the single-byte value 0x0a) is the line terminator character. This character always terminates a line of zig source code (except possbly the last line of the file).</p>8510 <p>The codepoint U+000a (LF) (which is encoded as the single-byte value 0x0a) is the line terminator character. This character always terminates a line of zig source code (except possbly the last line of the file).</p>
8434 <p>For some discussion on the rationale behind these design decisions, see <a href="https://github.com/ziglang/zig/issues/663">issue #663</a></p>8511 <p>For some discussion on the rationale behind these design decisions, see <a href="https://github.com/ziglang/zig/issues/663">issue #663</a></p>
8435 {#header_close#}8512 {#header_close#}
8513
8514 {#header_open|Keyword Reference#}
8515 <p>
8516 TODO the rest of the keywords. Most of these can just be links to the relevant section.
8517 </p>
8518 {#header_open|Keyword: pub#}
8519 <p>The {#syntax#}pub{#endsyntax#} in front of a top level declaration makes the
8520 declaration available to reference from a different file than the one it is declared in.</p>
8521 <p><a href="https://github.com/ziglang/zig/issues/2059">TODO delete pub syntax for fields, or make it do something.</a></p>
8522 {#see_also|@import#}
8523 {#header_close#}
8524 {#header_close#}
8525
8436 {#header_open|Grammar#}8526 {#header_open|Grammar#}
8437 <pre><code>Root &lt;- skip ContainerMembers eof8527 <pre><code>Root &lt;- skip ContainerMembers eof
84388528