diff options
| -rw-r--r-- | doc/langref.html.in | 75 |
1 files changed, 58 insertions, 17 deletions
diff --git a/doc/langref.html.in b/doc/langref.html.in index cdb37d5c24..374338d26e 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -413,7 +413,7 @@ pub fn main() !void { <p> The code sample shows the contents of a file named <code class="file">hello.zig</code>. Files storing Zig source code are {#link|UTF-8 encoded|Source Encoding#} text files. The files storing - Zig source code are usually named with the <code class="file"><em>.zig</em></code> extension. + Zig source code must be named with the <code class="file"><em>.zig</em></code> extension. </p> <p> Following the <code class="file">hello.zig</code> Zig code sample, the {#link|Zig Build System#} is used @@ -487,7 +487,7 @@ pub fn main() !void { 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 an {#link|tuple|Tuples#}). The <code>\n</code> + (known as a {#link|tuple|Tuples#}). The <code>\n</code> 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 @@ -518,6 +518,14 @@ pub fn main() void { {#see_also|Values|@import|Errors|Root Source File|Source Encoding#} {#header_close#} {#header_open|Comments#} + <p> + Zig supports 3 types of comments. Normal comments are ignored, but doc comments + and top-level doc comments are used by the compiler to generate the package documentation. + </p> + <p> + The generated documentation is still experimental, and can be produced with: + </p> + {#shell_samp#}zig test -femit-docs main.zig{#end_shell_samp#} {#code_begin|exe|comments#} const print = @import("std").debug.print; @@ -535,7 +543,7 @@ pub fn main() void { comments in C). This helps allow Zig to have the property that each line of code can be tokenized out of context. </p> - {#header_open|Doc comments#} + {#header_open|Doc Comments#} <p> A doc comment is one that begins with exactly three slashes (i.e. {#syntax#}///{#endsyntax#} but not {#syntax#}////{#endsyntax#}); @@ -562,21 +570,44 @@ const Timestamp = struct { }; {#code_end#} <p> - Doc comments are only allowed in certain places; eventually, it will - become a compile error to have a doc comment in an unexpected place, such as - in the middle of an expression, or just before a non-doc comment. + Doc comments are only allowed in certain places; it is a compile error to + have a doc comment in an unexpected place, such as in the middle of an expression, + or just before a non-doc comment. + </p> + {#code_begin|obj_err|invalid_doc-comment|expected type expression, found 'a document comment'#} +/// doc-comment +//! top-level doc-comment +const std = @import("std"); + {#code_end#} + {#code_begin|obj_err|unattached_doc-comment|unattached documentation comment#} +pub fn main() void {} + +/// End of file + {#code_end#} + <p> + Doc comments can be interleaved with normal comments. Currently, when producing + the package documentation, normal comments are merged with doc comments. </p> {#header_close#} {#header_open|Top-Level Doc Comments#} - <p>User documentation that doesn't belong to whatever - immediately follows it, like {#link|container|Containers#}-level documentation, goes - in top-level doc comments. A top-level doc comment is one that - begins with two slashes and an exclamation point: - {#syntax#}//!{#endsyntax#}.</p> + <p> + A top-level doc comment is one that begins with two slashes and an exclamation + point: {#syntax#}//!{#endsyntax#}; it documents the current module. + </p> + <p> + It is a compile error if a top-level doc comment is not placed at the start + of a {#link|container|Containers#}, before any expressions. + </p> {#code_begin|syntax|tldoc_comments#} //! This module provides functions for retrieving the current date and //! time with varying degrees of precision and accuracy. It does not //! depend on libc, but will use functions from it if available. + +const S = struct { + //! Top level comments are allowed inside a container other than a module, + //! but it is not very useful. Currently, when producing the package + //! documentation, these comments are ignored. +}; {#code_end#} {#header_close#} {#header_close#} @@ -1060,6 +1091,11 @@ test "expect addOne adds one to 41" { try std.testing.expect(addOne(41) == 42); } +test addOne { + // A test name can also be written using an identifier. + try std.testing.expect(addOne(41) == 42); +} + /// The function `addOne` adds one to the number given as its argument. fn addOne(number: i32) i32 { return number + 1; @@ -1087,20 +1123,25 @@ fn addOne(number: i32) i32 { printed to standard error by the default test runner: </p> <dl> - <dt><samp>Test [1/1] test "expect addOne adds one to 41"...</samp></dt> + <dt><samp>Test [1/2] test.expect addOne adds one to 41...</samp></dt> <dd>Lines like this indicate which test, out of the total number of tests, is being run. - In this case, <samp>[1/1]</samp> indicates that the first test, out of a total of - one test, is being run. Note that, when the test runner program's standard error is output + In this case, <samp>[1/2]</samp> indicates that the first test, out of a total of + two test, is being run. Note that, when the test runner program's standard error is output to the terminal, these lines are cleared when a test succeeds. </dd> - <dt><samp>All 1 tests passed.</samp></dt> + <dt><samp>Test [2/2] decltest.addOne...</samp></dt> + <dd>When the test name is an identifier, the default test runner uses the text + decltest instead of test. + </dd> + <dt><samp>All 2 tests passed.</samp></dt> <dd>This line indicates the total number of tests that have passed.</dd> </dl> {#header_open|Test Declarations#} <p> Test declarations contain the {#link|keyword|Keyword Reference#} {#syntax#}test{#endsyntax#}, followed by an - optional name written as a {#link|string literal|String Literals and Unicode Code Point Literals#}, followed - by a {#link|block|Blocks#} containing any valid Zig code that is allowed in a {#link|function|Functions#}. + optional name written as a {#link|string literal|String Literals and Unicode Code Point Literals#} or an + {#link|identifier|Identifiers#}, followed by a {#link|block|Blocks#} containing any valid Zig code that + is allowed in a {#link|function|Functions#}. </p> <aside> By convention, non-named tests should only be used to {#link|make other tests run|Nested Container Tests#}. |