Commit efbb6128bb

Manlio Perillo <manlio.perillo@gmail.com>
2023-01-19 12:33:00
langref: always start code on a separate line in a syntax_block
In a syntax_block the code always start on a separate code, expect for C, JavaScript, Peg and with Zig inline assembly. Ensure that the code starts on a separate line, even in cases where there is only one line. Ensure that the end_syntax_block is always on a separate line and that the indentation is consistent.
1 parent d87a58d
Changed files (1)
doc/langref.html.in
@@ -6045,14 +6045,16 @@ const optional_int: ?i32 = 5678;
       Task: call malloc, if the result is null, return null.
       </p>
       <p>C code</p>
-      {#syntax_block|c|call_malloc_in_c.c#}// malloc prototype included for reference
+      {#syntax_block|c|call_malloc_in_c.c#}
+// malloc prototype included for reference
 void *malloc(size_t size);
 
 struct Foo *do_a_thing(void) {
     char *ptr = malloc(1234);
     if (!ptr) return NULL;
     // ...
-}{#end_syntax_block#}
+}
+      {#end_syntax_block#}
       <p>Zig code</p>
       {#syntax_block|zig|call_malloc_from_zig.zig#}
 // malloc prototype included for reference
@@ -6072,7 +6074,8 @@ fn doAThing() ?*Foo {
       <p>
         The other form of checking against NULL you might see looks like this:
       </p>
-      {#syntax_block|c|checking_null_in_c.c#}void do_a_thing(struct Foo *foo) {
+      {#syntax_block|c|checking_null_in_c.c#}
+void do_a_thing(struct Foo *foo) {
     // do some stuff
 
     if (foo) {
@@ -6080,7 +6083,8 @@ fn doAThing() ?*Foo {
     }
 
     // do some stuff
-}{#end_syntax_block#}
+}
+      {#end_syntax_block#}
       <p>
         In Zig you can accomplish the same thing:
       </p>
@@ -7443,7 +7447,8 @@ pub fn syscall3(number: usize, arg1: usize, arg2: usize, arg3: usize) usize {
       <p>
       Dissecting the syntax:
       </p>
-      {#syntax_block|zig|Assembly Syntax Explained#}// Inline assembly is an expression which returns a value.
+      {#syntax_block|zig|Assembly Syntax Explained#}
+// Inline assembly is an expression which returns a value.
 // the `asm` keyword begins the expression.
 _ = asm
 // `volatile` is an optional modifier that tells Zig this
@@ -7498,7 +7503,8 @@ volatile (
 // output. In this example we list $rcx and $r11 because it is known the
 // kernel syscall does not preserve these registers.
     : "rcx", "r11"
-);{#end_syntax_block#}
+);
+      {#end_syntax_block#}
       <p>
       For x86 and x86_64 targets, the syntax is AT&amp;T syntax, rather than the more
       popular Intel syntax. This is due to technical constraints; assembly parsing is
@@ -10688,12 +10694,15 @@ const c = @cImport({
         or <kbd>-cflags</kbd> could result in clang or Zig parse failures, or subtle ABI incompatibilities
         when linking with C code.
       </p>
-      {#syntax_block|c|varytarget.h#}long FOO = __LONG_MAX__;{#end_syntax_block#}
+      {#syntax_block|c|varytarget.h#}
+long FOO = __LONG_MAX__;
+      {#end_syntax_block#}
       {#shell_samp#}$ zig translate-c -target thumb-freestanding-gnueabihf varytarget.h|grep FOO
 pub export var FOO: c_long = 2147483647;
 $ zig translate-c -target x86_64-macos-gnu varytarget.h|grep FOO
 pub export var FOO: c_long = 9223372036854775807;{#end_shell_samp#}
-      {#syntax_block|c|varycflags.h#}enum FOO { BAR };
+      {#syntax_block|c|varycflags.h#}
+enum FOO { BAR };
 int do_something(enum FOO foo);
       {#end_syntax_block#}
       {#shell_samp#}$ zig translate-c varycflags.h|grep -B1 do_something
@@ -10784,7 +10793,8 @@ pub fn main() void {
         Zig.
       </p>
       <p>Consider the following example:</p>
-      {#syntax_block|c|macro.c#}#define MAKELOCAL(NAME, INIT) int NAME = INIT
+      {#syntax_block|c|macro.c#}
+#define MAKELOCAL(NAME, INIT) int NAME = INIT
 int foo(void) {
    MAKELOCAL(a, 1);
    MAKELOCAL(b, 2);
@@ -10905,7 +10915,8 @@ export fn add(a: i32, b: i32) i32 {
       <p>To make a shared library:</p>
       {#shell_samp#}$ zig build-lib mathtest.zig -dynamic{#end_shell_samp#}
       <p>Here is an example with the {#link|Zig Build System#}:</p>
-      {#syntax_block|c|test.c#}// This header is generated by zig from mathtest.zig
+      {#syntax_block|c|test.c#}
+// This header is generated by zig from mathtest.zig
 #include "mathtest.h"
 #include <stdio.h>
 
@@ -10959,7 +10970,8 @@ export fn decode_base_64(
     return decoded_size;
 }
       {#code_end#}
-      {#syntax_block|c|test.c#}// This header is generated by zig from base64.zig
+      {#syntax_block|c|test.c#}
+// This header is generated by zig from base64.zig
 #include "base64.h"
 
 #include <string.h>
@@ -11009,7 +11021,8 @@ export fn add(a: i32, b: i32) void {
     print(a + b);
 }
       {#code_end#}
-      {#syntax_block|javascript|test.js#}const fs = require('fs');
+      {#syntax_block|javascript|test.js#}
+const fs = require('fs');
 const source = fs.readFileSync("./math.wasm");
 const typedArray = new Uint8Array(source);
 
@@ -11019,8 +11032,9 @@ WebAssembly.instantiate(typedArray, {
   }}).then(result => {
   const add = result.instance.exports.add;
   add(1, 2);
-});{#end_syntax_block#}
-    {#shell_samp#}$ node test.js
+});
+      {#end_syntax_block#}
+      {#shell_samp#}$ node test.js
 The result is 3{#end_shell_samp#}
       {#header_close#}
       {#header_open|WASI#}
@@ -12065,7 +12079,8 @@ fn readU32Be() u32 {}
       {#header_close#}
 
       {#header_open|Grammar#}
-      {#syntax_block|peg|grammar.y#}Root <- skip container_doc_comment? ContainerMembers eof
+      {#syntax_block|peg|grammar.y#}
+Root <- skip container_doc_comment? ContainerMembers eof
 
 # *** Top level ***
 ContainerMembers <- ContainerDeclarations (ContainerField COMMA)* (ContainerField / ContainerDeclarations)
@@ -12631,7 +12646,7 @@ keyword <- KEYWORD_addrspace / KEYWORD_align / KEYWORD_allowzero / KEYWORD_and
          / KEYWORD_struct / KEYWORD_suspend / KEYWORD_switch / KEYWORD_test
          / KEYWORD_threadlocal / KEYWORD_try / KEYWORD_union / KEYWORD_unreachable
          / KEYWORD_usingnamespace / KEYWORD_var / KEYWORD_volatile / KEYWORD_while
-{#end_syntax_block#}
+      {#end_syntax_block#}
       {#header_close#}
       {#header_open|Zen#}
       <ul>