From f5978181e41e272b5c272440b9c543ead0357e2e Mon Sep 17 00:00:00 2001 From: Scott Schwarz Date: Mon, 8 Jan 2024 00:32:26 -0600 Subject: [PATCH] langref: reword Hello World section (#18458) closes #14347 --- doc/langref.html.in | 49 +++++++++++++++++++++------------------------ 1 file changed, 23 insertions(+), 26 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index 7b5d086f2d..4200917508 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -432,18 +432,17 @@ pub fn main() !void {

Next, a {#link|public function|Functions#}, {#syntax#}pub fn{#endsyntax#}, named {#syntax#}main{#endsyntax#} - is declared. The {#syntax#}main{#endsyntax#} function is necessary because it tells the Zig compiler where the start of - the program exists. Programs designed to be executed will need a {#syntax#}pub fn main{#endsyntax#} function. + is declared. The {#syntax#}main{#endsyntax#} function is necessary because it tells the Zig compiler where the program starts. Programs + designed to be executed will need a {#syntax#}pub fn main{#endsyntax#} function.

- A function is a block of any number of statements and expressions that, as a whole, perform a task. + A function is a block of any number of statements and expressions, that as a whole, perform a task. Functions may or may not return data after they are done performing their task. If a function cannot perform its task, it might return an error. Zig makes all of this explicit.

@@ -469,32 +468,30 @@ pub fn main() !void {

In Zig, a function's block of statements and expressions are surrounded by an open curly-brace { and - close curly-brace }. Inside of the {#syntax#}main{#endsyntax#} function are expressions that perform - the task of outputting Hello, world! to standard output. + close curly-brace }. In hello.zig, the {#syntax#}main{#endsyntax#} function + contains two statements.

- First, a constant identifier, {#syntax#}stdout{#endsyntax#}, is initialized to represent standard output's - writer. Then, the program tries to print the Hello, world! - message to standard output. + In the first statement, a constant identifier, {#syntax#}stdout{#endsyntax#}, is initialized to represent standard output's + writer. In the second statement, the program tries to print the Hello, world! message to standard output.

- Functions sometimes need information to perform their task. In Zig, information is passed - to functions between an open parenthesis {#syntax#}({#endsyntax#} and a close parenthesis {#syntax#}){#endsyntax#} placed after - the function's name. This information is also known as arguments. When there are - multiple arguments passed to a function, they are separated by commas {#syntax#},{#endsyntax#}. + Functions sometimes need inputs to perform their task. Inputs are passed, in between parentheses, to functions. These + inputs are also known as arguments. When multiple arguments are passed to a function, they are separated by commas.

- The two arguments passed to the {#syntax#}stdout.print(){#endsyntax#} function, {#syntax#}"Hello, {s}!\n"{#endsyntax#} - and {#syntax#}.{"world"}{#endsyntax#}, are evaluated at {#link|compile-time|comptime#}. The code sample is - purposely written to show how to perform {#link|string|String Literals and Unicode Code Point Literals#} - substitution in the {#syntax#}print{#endsyntax#} function. The curly-braces inside of the first argument - are substituted with the compile-time known value inside of the second argument - (known as a {#link|tuple|Tuples#}). The \n - inside of the double-quotes of the first argument is the {#link|escape sequence|Escape Sequences#} for the - newline character. The {#link|try#} expression evaluates the result of {#syntax#}stdout.print{#endsyntax#}. - If the result is an error, then the {#syntax#}try{#endsyntax#} expression will return from - {#syntax#}main{#endsyntax#} with the error. Otherwise, the program will continue. In this case, there are no - more statements or expressions left to execute in the {#syntax#}main{#endsyntax#} function, so the program exits. + Two arguments are passed to the {#syntax#}stdout.print(){#endsyntax#} function: {#syntax#}"Hello, {s}!\n"{#endsyntax#} + and {#syntax#}.{"world"}{#endsyntax#}. The first argument is called a format string, which is a string containing one or + more placeholders. {#syntax#}"Hello, {s}!\n"{#endsyntax#} contains the placeholder {#syntax#}{s}{#endsyntax#}, which is + replaced with {#syntax#}"world"{#endsyntax#} from the second argument. The file string_literals.zig in + {#link|String Literals and Unicode Code Point Literals|String Literals and Unicode Code Point Literals#} contains examples of format + strings that can be used with the {#syntax#}stdout.print(){#endsyntax#} function. The \n inside of + {#syntax#}"Hello, {s}!\n"{#endsyntax#} is the {#link|escape sequence|Escape Sequences#} for the newline character. +

+

+ The {#link|try#} expression evaluates the result of {#syntax#}stdout.print{#endsyntax#}. If the result is an error, then the + {#syntax#}try{#endsyntax#} expression will return from {#syntax#}main{#endsyntax#} with the error. Otherwise, the program will continue. + In this case, there are no more statements or expressions left to execute in the {#syntax#}main{#endsyntax#} function, so the program exits.

In Zig, the standard output writer's {#syntax#}print{#endsyntax#} function is allowed to fail because