From 7d6ed1cd854422613f0bf9dc8d54362dec4eca98 Mon Sep 17 00:00:00 2001 From: extrasharp Date: Mon, 24 Aug 2020 10:59:55 -0500 Subject: [PATCH 01/56] Add Keyword Reference section --- doc/langref.html.in | 570 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 562 insertions(+), 8 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index 8e324743ea..790a8e14c4 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -10308,14 +10308,568 @@ fn readU32Be() u32 {} {#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.

- {#see_also|@import#} - {#header_close#} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Keyword + + Description +
+ 
{#syntax#}align{#endsyntax#}
+ 		+ {#syntax#}align{#endsyntax#} can be used to specify the alignment of a pointer. It can also be used after a variable or function declaration to specify the alignment of pointers to that variable or function. +
    +
  • See also {#link|Alignment#}
    • +
+
+ 
{#syntax#}allowzero{#endsyntax#}
+ 		+ The pointer attribute {#syntax#}allowzero{#endsyntax#} allows a pointer to have address zero. +
    +
  • See also {#link|allowzero#}
    • +
+
+ 
{#syntax#}and{#endsyntax#}
+ 		+ The boolean operator {#syntax#}and{#endsyntax#}. +
    +
  • See also {#link|Operators#}
    • +
+
+ 
{#syntax#}anyframe{#endsyntax#}
+ 		+ {#syntax#}anyframe{#endsyntax#} can be used as a type for variables which hold pointers to function frames. +
    +
  • See also {#link|Async Functions#}
    • +
+
+ 
{#syntax#}anytype{#endsyntax#}
+ 		+ Function parameters can be declared with {#syntax#}anytype{#endsyntax#} in place of the type. The parameter type will be inferred where the function is called. +
    +
  • See also {#link|Function Parameter Type Inference#}
    • +
+
+ 
{#syntax#}asm{#endsyntax#}
+ 		+ {#syntax#}asm{#endsyntax#} begins an inline assembly expression. This allows for directly controlling the machine code generated on compilation. +
    +
  • See also {#link|Assembly#}
    • +
+
+ 
{#syntax#}async{#endsyntax#}
+ 		+ {#syntax#}async{#endsyntax#} can be used before a function call to get a pointer to the function's frame when it suspends. +
    +
  • See also {#link|Async Functions#}
    • +
+
+ 
{#syntax#}await{#endsyntax#}
+ 		+ {#syntax#}await{#endsyntax#} can be used to suspend the current function until the frame provided after the {#syntax#}await{#endsyntax#} completes. {#syntax#}await{#endsyntax#} copies the value returned from the target function's frame to the caller. +
    +
  • See also {#link|Async Functions#}
    • +
+
+ 
{#syntax#}break{#endsyntax#}
+ 		+ {#syntax#}break{#endsyntax#} can be used to exit a loop before iteration completes naturally. + It can also be used with a block label to return a value from the block. +
    +
  • See also {#link|blocks#}, {#link|while#}, {#link|for#}
    • +
+
+ 
{#syntax#}catch{#endsyntax#}
+ 		+ {#syntax#}catch{#endsyntax#} can be used to provide a default value for an error union, or capture its error value in an expression. +
    +
  • See also {#link|catch#}, {#link|Operators#}
    • +
+
+ 
{#syntax#}comptime{#endsyntax#}
+ 		+ {#syntax#}comptime{#endsyntax#} before a declaration can be used to label variables or function parameters as known at compile time. + It can also be used to guarantee an expression is run at compile time. +
    +
  • See also {#link|comptime#}
    • +
+
+ 
{#syntax#}const{#endsyntax#}
+ 		+ {#syntax#}const{#endsyntax#} declares a variable that can not be modified. +
    +
  • See also {#link|Variables#}
    • +
+
+ 
{#syntax#}continue{#endsyntax#}
+ 		+ {#syntax#}continue{#endsyntax#} can be used in a loop to jump back to the beginning of the loop. +
    +
  • See also {#link|while#}, {#link|for#}
    • +
+
+ 
{#syntax#}defer{#endsyntax#}
+ 		+ {#syntax#}defer{#endsyntax#} will execute an expression at the end of the current block. +
    +
  • See also {#link|defer#}
    • +
+
+ 
{#syntax#}else{#endsyntax#}
+ 		+ {#syntax#}else{#endsyntax#} can be used to provide an alternate branch for {#syntax#}if{#endsyntax#}, {#syntax#}switch{#endsyntax#}, {#syntax#}while{#endsyntax#}, and {#syntax#}for{#endsyntax#} expressions. +
    +
  • If used after an if expression, the else branch will be executed if the test value returns false, null, or an error.
    • +
  • If used within a switch expression, the else branch will be executed if the test value matches no other cases.
    • +
  • If used after a loop expression, the else branch will be executed if the loop finishes without breaking.
    • +
  • See also {#link|if#}, {#link|switch#}, {#link|while#}, {#link|for#}
    • +
+
+ 
{#syntax#}enum{#endsyntax#}
+ 		+ {#syntax#}enum{#endsyntax#} defines an anonymous enum type. +
    +
  • See also {#link|enum#}
    • +
+
+ 
{#syntax#}errdefer{#endsyntax#}
+ 		+ {#syntax#}errdefer{#endsyntax#} will execute an expression at the end of the current block if and only if the block returns an error. +
    +
  • See also {#link|errdefer#}
    • +
+
+ 
{#syntax#}error{#endsyntax#}
+ 		+ {#syntax#}error{#endsyntax#} defines an anonymous error type. +
    +
  • See also {#link|Errors#}
    • +
+
+ 
{#syntax#}export{#endsyntax#}
+ 		+ {#syntax#}export{#endsyntax#} makes a function externally visible in the generated object file, and makes it use the C ABI. +
    +
  • See also {#link|Functions#}
    • +
+
+ 
{#syntax#}extern{#endsyntax#}
+ 		+ {#syntax#}extern{#endsyntax#} can be used to declare a function that will be resolved at link time, when linking statically, or at runtime, when linking dynamically. +
    +
  • See also {#link|Functions#}
    • +
+
+ 
{#syntax#}false{#endsyntax#}
+ 		+ The boolean value {#syntax#}false{#endsyntax#}. +
    +
  • See also {#link|Primitive Values#}
    • +
+
+ 
{#syntax#}fn{#endsyntax#}
+ 		+ {#syntax#}fn{#endsyntax#} declares a function. +
    +
  • See also {#link|Functions#}
    • +
+
+ 
{#syntax#}for{#endsyntax#}
+ 		+ A {#syntax#}for{#endsyntax#} expression can be used to iterate over the elements of a slice or array. +
    +
  • See also {#link|for#}
    • +
+
+ 
{#syntax#}if{#endsyntax#}
+ 		+ An {#syntax#}if{#endsyntax#} expression can test boolean expressions, optional values, or error unions. + For optional values or error unions, the if expression can capture the unwrapped value. +
    +
  • See also {#link|if#}
    • +
+
+ 
{#syntax#}inline{#endsyntax#}
+ 		+ {#syntax#}inline{#endsyntax#} can be used to label a loop expression such that it will be unrolled at compile time. + It can also be used to force a function to be inlined at all call sites. +
    +
  • See also {#link|inline while#}, {#link|inline for#}, {#link|Functions#}
    • +
+
+ 
{#syntax#}noalias{#endsyntax#}
+ 		+ The {#syntax#}noalias{#endsyntax#} keyword. +
    +
  • TODO add documentation for noalias
    • +
+
+ 
{#syntax#}nosuspend{#endsyntax#}
+ 		+ The {#syntax#}nosuspend{#endsyntax#} keyword. +
    +
  • TODO add documentation for nosuspend
    • +
+
+ 
{#syntax#}null{#endsyntax#}
+ 		+ The optional value {#syntax#}null{#endsyntax#}. +
    +
  • See also {#link|null#}
    • +
+
+ 
{#syntax#}or{#endsyntax#}
+ 		+ The boolean operator {#syntax#}or{#endsyntax#}. +
    +
  • See also {#link|Operators#}
    • +
+
+ 
{#syntax#}orelse{#endsyntax#}
+ 		+ {#syntax#}orelse{#endsyntax#} can be used to provide a default value for an optional expression if it evaluates to null. +
    +
  • See also {#link|Optionals#}, {#link|Operators#}
    • +
+
+ 
{#syntax#}packed{#endsyntax#}
+ 		+ The {#syntax#}packed{#endsyntax#} keyword before a struct definition changes the struct's in-memory layout to the guaranteed {#syntax#}packed{#endsyntax#} layout. +
    +
  • See also {#link|packed struct#}
    • +
+
+ 
{#syntax#}pub{#endsyntax#}
+ 		+ 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. +
    +
  • See also {#link|import#}
    • +
+
+ 
{#syntax#}resume{#endsyntax#}
+ 		+ {#syntax#}resume{#endsyntax#} will continue execution of a function frame after the point the function was suspended. +
    +
  • See also {#link|Suspend and Resume#}
    • +
+
+ 
{#syntax#}return{#endsyntax#}
+ 		+ {#syntax#}return{#endsyntax#} exits a function with a value. +
    +
  • See also {#link|Functions#}
    • +
+
+ 
{#syntax#}linksection{#endsyntax#}
+ 		+ The {#syntax#}linksection{#endsyntax#} keyword. +
    +
  • TODO add documentation for linksection
    • +
+
+ 
{#syntax#}struct{#endsyntax#}
+ 		+ {#syntax#}struct{#endsyntax#} defines an anonymous struct. +
    +
  • See also {#link|struct#}
    • +
+
+ 
{#syntax#}suspend{#endsyntax#}
+ 		+ {#syntax#}suspend{#endsyntax#} will cause control flow to return to the call site or resumer of the function. + {#syntax#}suspend{#endsyntax#} can also be used before a block within a function, to allow the function access to it's frame before control flow returns to the call site. +
    +
  • See also {#link|Suspend and Resume#}
    • +
+
+ 
{#syntax#}switch{#endsyntax#}
+ 		+ A {#syntax#}switch{#endsyntax#} expression can be used to test values of a common type. {#syntax#}switch{#endsyntax#} cases can capture field values of a {#link|Tagged union#}. +
    +
  • See also {#link|switch#}
    • +
+
+ 
{#syntax#}test{#endsyntax#}
+ 		+ The {#syntax#}test{#endsyntax#} keyword can be used to denote a top-level block of code used to make sure behavior meets expectations. +
    +
  • See also {#link|Zig Test#}
    • +
+
+ 
{#syntax#}threadlocal{#endsyntax#}
+ 		+ {#syntax#}threadlocal{#endsyntax#} can be used to specify a variable as thread-local. +
    +
  • See also {#link|Thread Local Variables#}
    • +
+
+ 
{#syntax#}true{#endsyntax#}
+ 		+ The boolean value {#syntax#}true{#endsyntax#}. +
    +
  • See also {#link|Primitive Values#}
    • +
+
+ 
{#syntax#}try{#endsyntax#}
+ 		+ {#syntax#}try{#endsyntax#} evaluates an error union expression. + If it is an error, it returns from the current function with the same error. + Otherwise, the expression results in the unwrapped value. +
    +
  • See also {#link|try#}
    • +
+
+ 
{#syntax#}undefined{#endsyntax#}
+ 		+ {#syntax#}undefined{#endsyntax#} can be used to leave a value uninitialized. +
    +
  • See also {#link|undefined#}
    • +
+
+ 
{#syntax#}union{#endsyntax#}
+ 		+ {#syntax#}union{#endsyntax#} defines an anonymous union. +
    +
  • See also {#link|union#}
    • +
+
+ 
{#syntax#}unreachable{#endsyntax#}
+ 		+ Depending on the build mode, {#syntax#}unreachable{#endsyntax#} may emit a panic. +
    +
  • Emits a panic in {#syntax#}Debug{#endsyntax#} and {#syntax#}ReleaseSafe{#endsyntax#} mode, or when using zig test.
    • +
  • Does not emit a panic in {#syntax#}ReleaseFast{#endsyntax#} mode, unless zig test is being used.
    • +
  • See also {#link|unreachable#}
    • +
+
+ 
{#syntax#}usingnamespace{#endsyntax#}
+ 		+ {#syntax#}usingnamespace{#endsyntax#} is a top-level declaration that imports all the public declarations of the operand, which must be a struct, union, or enum, into the current scope. +
    +
  • See also {#link|usingnamespace#}
    • +
+
+ 
{#syntax#}var{#endsyntax#}
+ 		+ {#syntax#}var{#endsyntax#} declares a variable that may be modified. +
    +
  • See also {#link|Variables#}
    • +
+
+ 
{#syntax#}volatile{#endsyntax#}
+ 		+ {#syntax#}volatile{#endsyntax#} can be used to denote loads or stores of a pointer have side effects. + It can also modify an inline assembly expression to denote it has side effects. +
    +
  • See also {#link|volatile#}, {#link|Assembly#}
    • +
+
+ 
{#syntax#}while{#endsyntax#}
+ 		+ A {#syntax#}while{#endsyntax#} expression can be used to repeatedly test a boolean, optional, or error union expression, and cease looping when that expression evaluates to false, null, or an error, respectively. +
    +
  • See also {#link|while#}
    • +
+
{#header_close#} {#header_open|Grammar#} From 4d1710c8993b6834bf17bf68fe8cb481c7a8aae9 Mon Sep 17 00:00:00 2001 From: extrasharp Date: Mon, 24 Aug 2020 13:12:23 -0500 Subject: [PATCH 02/56] Make changes --- doc/langref.html.in | 64 ++++++++++++++++++++++++++++----------------- 1 file changed, 40 insertions(+), 24 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index 790a8e14c4..f1141bf22d 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -10322,7 +10322,8 @@ fn readU32Be() u32 {} 
{#syntax#}align{#endsyntax#}
- {#syntax#}align{#endsyntax#} can be used to specify the alignment of a pointer. It can also be used after a variable or function declaration to specify the alignment of pointers to that variable or function. + {#syntax#}align{#endsyntax#} can be used to specify the alignment of a pointer. + It can also be used after a variable or function declaration to specify the alignment of pointers to that variable or function. @@ -10366,7 +10367,8 @@ fn readU32Be() u32 {} 
{#syntax#}anytype{#endsyntax#}
- Function parameters can be declared with {#syntax#}anytype{#endsyntax#} in place of the type. The parameter type will be inferred where the function is called. + Function parameters and struct fields can be declared with {#syntax#}anytype{#endsyntax#} in place of the type. + The type will be inferred where the function is called or the struct is instantiated. @@ -10399,7 +10401,8 @@ fn readU32Be() u32 {} 
{#syntax#}await{#endsyntax#}
- {#syntax#}await{#endsyntax#} can be used to suspend the current function until the frame provided after the {#syntax#}await{#endsyntax#} completes. {#syntax#}await{#endsyntax#} copies the value returned from the target function's frame to the caller. + {#syntax#}await{#endsyntax#} can be used to suspend the current function until the frame provided after the {#syntax#}await{#endsyntax#} completes. + {#syntax#}await{#endsyntax#} copies the value returned from the target function's frame to the caller. @@ -10410,8 +10413,8 @@ fn readU32Be() u32 {} 
{#syntax#}break{#endsyntax#}
- {#syntax#}break{#endsyntax#} can be used to exit a loop before iteration completes naturally. - It can also be used with a block label to return a value from the block. + {#syntax#}break{#endsyntax#} can be used with a block label to return a value from the block. + It can also be used to exit a loop before iteration completes naturally. @@ -10422,7 +10425,8 @@ fn readU32Be() u32 {} 
{#syntax#}catch{#endsyntax#}
- {#syntax#}catch{#endsyntax#} can be used to provide a default value for an error union, or capture its error value in an expression. + {#syntax#}catch{#endsyntax#} can be used to evaluate an expression if the expression before it evaluates to an error. + The expression after the {#syntax#}catch{#endsyntax#} can optionally capture the error value. @@ -10446,6 +10450,7 @@ fn readU32Be() u32 {} {#syntax#}const{#endsyntax#} declares a variable that can not be modified. + Used as a pointer attribute, it denotes the value referenced by the pointer cannot be modified. @@ -10467,7 +10472,7 @@ fn readU32Be() u32 {} 
{#syntax#}defer{#endsyntax#}
- {#syntax#}defer{#endsyntax#} will execute an expression at the end of the current block. + {#syntax#}defer{#endsyntax#} will execute an expression when control flow leaves the current block. @@ -10478,7 +10483,8 @@ fn readU32Be() u32 {} 
{#syntax#}else{#endsyntax#}
- {#syntax#}else{#endsyntax#} can be used to provide an alternate branch for {#syntax#}if{#endsyntax#}, {#syntax#}switch{#endsyntax#}, {#syntax#}while{#endsyntax#}, and {#syntax#}for{#endsyntax#} expressions. + {#syntax#}else{#endsyntax#} can be used to provide an alternate branch for {#syntax#}if{#endsyntax#}, {#syntax#}switch{#endsyntax#}, + {#syntax#}while{#endsyntax#}, and {#syntax#}for{#endsyntax#} expressions.