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 {
58905890 {#see_also|Import from C Header File|@cInclude|@cImport|@cUndef|void#}
58915891 {#header_close#}
58925892 {#header_open|@cImport#}
5893 <pre>{#syntax#}@cImport(expression) (namespace){#endsyntax#}</pre>
5893 <pre>{#syntax#}@cImport(expression) type{#endsyntax#}</pre>
58945894 <p>
5895 This function parses C code and imports the functions, types, variables, and
5896 compatible macro definitions into the result namespace.
5895 This function parses C code and imports the functions, types, variables,
5896 and compatible macro definitions into a new empty struct type, and then
5897 returns that type.
58975898 </p>
58985899 <p>
58995900 {#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 {}
63206321 {#header_close#}
63216322
63226323 {#header_open|@import#}
6323 <pre>{#syntax#}@import(comptime path: []u8) (namespace){#endsyntax#}</pre>
6324 <pre>{#syntax#}@import(comptime path: []u8) type{#endsyntax#}</pre>
63246325 <p>
6325 This function finds a zig file corresponding to {#syntax#}path{#endsyntax#} and imports all the
6326 public top level declarations into the resulting namespace.
6326 This function finds a zig file corresponding to {#syntax#}path{#endsyntax#} and adds it to the build,
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.
63276336 </p>
63286337 <p>
63296338 {#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#}
63316340 function call.
63326341 </p>
63336342 <p>
......@@ -6335,7 +6344,9 @@ export fn @"A function name that is a complete sentence."() void {}
63356344 </p>
63366345 <ul>
63376346 <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>
63396350 </ul>
63406351 {#see_also|Compile Variables|@embedFile#}
63416352 {#header_close#}
......@@ -8177,28 +8188,68 @@ all your base are belong to us</code></pre>
81778188 </p>
81788189 <pre><code class="shell">$ zig targets
81798190Architectures:
8180 armv8_2a
8181 armv8_1a
8182 armv8
8183 armv8r
8184 armv8m_baseline
8185 armv8m_mainline
8186 armv7
8187 armv7em
8188 armv7m
8189 armv7s
8190 armv7k
8191 armv7ve
8192 armv6
8193 armv6m
8194 armv6k
8195 armv6t2
8196 armv5
8197 armv5te
8198 armv4t
8191 arm
8192 v8_4a
8193 v8_3a
8194 v8_2a
8195 v8_1a
8196 v8
8197 v8r
8198 v8m_baseline
8199 v8m_mainline
8200 v7
8201 v7em
8202 v7m
8203 v7s
8204 v7k
8205 v7ve
8206 v6
8207 v6m
8208 v6k
8209 v6t2
8210 v5
8211 v5te
8212 v4t
81998213 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
82008235 aarch64
8236 v8_4a
8237 v8_3a
8238 v8_2a
8239 v8_1a
8240 v8
8241 v8r
8242 v8m_baseline
8243 v8m_mainline
82018244 aarch64_be
8245 v8_4a
8246 v8_3a
8247 v8_2a
8248 v8_1a
8249 v8
8250 v8r
8251 v8m_baseline
8252 v8m_mainline
82028253 avr
82038254 bpfel
82048255 bpfeb
......@@ -8208,7 +8259,6 @@ Architectures:
82088259 mips64
82098260 mips64el
82108261 msp430
8211 nios2
82128262 powerpc
82138263 powerpc64
82148264 powerpc64le
......@@ -8220,32 +8270,58 @@ Architectures:
82208270 sparcv9
82218271 sparcel
82228272 s390x
8223 tce
8224 tcele
82258273 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
82268295 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
82278317 i386
82288318 x86_64 (native)
82298319 xcore
82308320 nvptx
82318321 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
82448322 lanai
82458323 wasm32
82468324 wasm64
8247 renderscript32
8248 renderscript64
82498325
82508326Operating Systems:
82518327 freestanding
......@@ -8268,7 +8344,6 @@ Operating Systems:
82688344 rtems
82698345 nacl
82708346 cnk
8271 bitrig
82728347 aix
82738348 cuda
82748349 nvcl
......@@ -8279,11 +8354,14 @@ Operating Systems:
82798354 watchos
82808355 mesa3d
82818356 contiki
8357 amdpal
82828358 zen
8359 uefi
82838360
8284Environments:
8285 unknown
8361C ABIs:
8362 none
82868363 gnu (native)
8364 gnuabin32
82878365 gnuabi64
82888366 gnueabi
82898367 gnueabihf
......@@ -8298,9 +8376,8 @@ Environments:
82988376 msvc
82998377 itanium
83008378 cygnus
8301 amdopencl
83028379 coreclr
8303 opencl</code></pre>
8380 simulator</code></pre>
83048381 <p>
83058382 The Zig Standard Library ({#syntax#}@import("std"){#endsyntax#}) has architecture, environment, and operating system
83068383 abstractions, and thus takes additional work to support more platforms.
......@@ -8433,6 +8510,19 @@ fn readU32Be() u32 {}
84338510 <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>
84348511 <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>
84358512 {#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
84368526 {#header_open|Grammar#}
84378527 <pre><code>Root &lt;- skip ContainerMembers eof
84388528