From 0588fed15f64cc7d53eff2c599beb63ae2a589a0 Mon Sep 17 00:00:00 2001 From: Andrew Kelley Date: Wed, 13 Mar 2019 13:04:55 -0400 Subject: [PATCH] add documentation for `pub` closes #1727 --- doc/langref.html.in | 188 ++++++++++++++++++++++++++++++++------------ 1 file changed, 139 insertions(+), 49 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index acf621c33f..f9e053ee17 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -5890,10 +5890,11 @@ comptime { {#see_also|Import from C Header File|@cInclude|@cImport|@cUndef|void#} {#header_close#} {#header_open|@cImport#} - 
{#syntax#}@cImport(expression) (namespace){#endsyntax#}
+ 
{#syntax#}@cImport(expression) type{#endsyntax#}

- This function parses C code and imports the functions, types, variables, and - compatible macro definitions into the result namespace. + This function parses C code and imports the functions, types, variables, + and compatible macro definitions into a new empty struct type, and then + returns that type.

{#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 {} {#header_close#} {#header_open|@import#} - 

{#syntax#}@import(comptime path: []u8) (namespace){#endsyntax#}
+ 
{#syntax#}@import(comptime path: []u8) type{#endsyntax#}

- This function finds a zig file corresponding to {#syntax#}path{#endsyntax#} and imports all the - public top level declarations into the resulting namespace. + This function finds a zig file corresponding to {#syntax#}path{#endsyntax#} and adds it to the build, + if it is not already added. +

+

+ Zig source files are implicitly structs, with a name equal to the file's basename with the extension + truncated. {#syntax#}@import{#endsyntax#} returns the struct type corresponding to the file. +

+

+ Declarations which have the {#syntax#}pub{#endsyntax#} keyword may be referenced from a different + source file than the one they are declared in.

{#syntax#}path{#endsyntax#} can be a relative or absolute path, or it can be the name of a package. - If it is a relative path, it is relative to the file that contains the {#syntax#}@import{#endsyntax#} + If it is a relative path, it is relative to the file that contains the {#syntax#}@import{#endsyntax#} function call.

@@ -6335,7 +6344,9 @@ export fn @"A function name that is a complete sentence."() void {}

{#see_also|Compile Variables|@embedFile#} {#header_close#} @@ -8177,28 +8188,68 @@ all your base are belong to us 

$ zig targets
 Architectures:
-  armv8_2a
-  armv8_1a
-  armv8
-  armv8r
-  armv8m_baseline
-  armv8m_mainline
-  armv7
-  armv7em
-  armv7m
-  armv7s
-  armv7k
-  armv7ve
-  armv6
-  armv6m
-  armv6k
-  armv6t2
-  armv5
-  armv5te
-  armv4t
+  arm
+    v8_4a
+    v8_3a
+    v8_2a
+    v8_1a
+    v8
+    v8r
+    v8m_baseline
+    v8m_mainline
+    v7
+    v7em
+    v7m
+    v7s
+    v7k
+    v7ve
+    v6
+    v6m
+    v6k
+    v6t2
+    v5
+    v5te
+    v4t
   armeb
+    v8_4a
+    v8_3a
+    v8_2a
+    v8_1a
+    v8
+    v8r
+    v8m_baseline
+    v8m_mainline
+    v7
+    v7em
+    v7m
+    v7s
+    v7k
+    v7ve
+    v6
+    v6m
+    v6k
+    v6t2
+    v5
+    v5te
+    v4t
   aarch64
+    v8_4a
+    v8_3a
+    v8_2a
+    v8_1a
+    v8
+    v8r
+    v8m_baseline
+    v8m_mainline
   aarch64_be
+    v8_4a
+    v8_3a
+    v8_2a
+    v8_1a
+    v8
+    v8r
+    v8m_baseline
+    v8m_mainline
   avr
   bpfel
   bpfeb
@@ -8208,7 +8259,6 @@ Architectures:
   mips64
   mips64el
   msp430
-  nios2
   powerpc
   powerpc64
   powerpc64le
@@ -8220,32 +8270,58 @@ Architectures:
   sparcv9
   sparcel
   s390x
-  tce
-  tcele
   thumb
+    v8_4a
+    v8_3a
+    v8_2a
+    v8_1a
+    v8
+    v8r
+    v8m_baseline
+    v8m_mainline
+    v7
+    v7em
+    v7m
+    v7s
+    v7k
+    v7ve
+    v6
+    v6m
+    v6k
+    v6t2
+    v5
+    v5te
+    v4t
   thumbeb
+    v8_4a
+    v8_3a
+    v8_2a
+    v8_1a
+    v8
+    v8r
+    v8m_baseline
+    v8m_mainline
+    v7
+    v7em
+    v7m
+    v7s
+    v7k
+    v7ve
+    v6
+    v6m
+    v6k
+    v6t2
+    v5
+    v5te
+    v4t
   i386
   x86_64 (native)
   xcore
   nvptx
   nvptx64
-  le32
-  le64
-  amdil
-  amdil64
-  hsail
-  hsail64
-  spir
-  spir64
-  kalimbav3
-  kalimbav4
-  kalimbav5
-  shave
   lanai
   wasm32
   wasm64
-  renderscript32
-  renderscript64
 
 Operating Systems:
   freestanding
@@ -8268,7 +8344,6 @@ Operating Systems:
   rtems
   nacl
   cnk
-  bitrig
   aix
   cuda
   nvcl
@@ -8279,11 +8354,14 @@ Operating Systems:
   watchos
   mesa3d
   contiki
+  amdpal
   zen
+  uefi
 
-Environments:
-  unknown
+C ABIs:
+  none
   gnu (native)
+  gnuabin32
   gnuabi64
   gnueabi
   gnueabihf
@@ -8298,9 +8376,8 @@ Environments:
   msvc
   itanium
   cygnus
-  amdopencl
   coreclr
-  opencl
+ simulator

The Zig Standard Library ({#syntax#}@import("std"){#endsyntax#}) has architecture, environment, and operating system abstractions, and thus takes additional work to support more platforms. @@ -8433,6 +8510,19 @@ fn readU32Be() u32 {}

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).

For some discussion on the rationale behind these design decisions, see issue #663

{#header_close#} + + {#header_open|Keyword Reference#} +

+ TODO the rest of the keywords. Most of these can just be links to the relevant section. +

+ {#header_open|Keyword: pub#} +

The {#syntax#}pub{#endsyntax#} in front of a top level declaration makes the + declaration available to reference from a different file than the one it is declared in.

+

TODO delete pub syntax for fields, or make it do something.

+ {#see_also|@import#} + {#header_close#} + {#header_close#} + {#header_open|Grammar#} 
Root <- skip ContainerMembers eof