mirror/zig
1
0
Fork 0
mirror of https://github.com/ziglang/zig.git synced 2026-02-20 00:08:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

Langref misc fix and improvement (#14695)

Browse Source 
* langref: improve the Hello World section

Clarify that a Zig source file must have the .zig extension.

Fix a typo.

* langref: improve the Comments section

  - Document how doc comments are used by -femit-docs
  - Rename "Doc comments" to "Doc Comments", for consistency
  - Clarify that placing a doc comment in an unexpected place is a
    compiler error and add two incorrect examples
  - Document the current Autodoc behavior, when normal comments are
    interleaved with doc comments
  - Rewrite the documentation for top-level doc comments

* langref: improve the Zig Test section

Document that the test name can also be an identifier, in addition to a
string literal.

Update the test output for the first test.

Closes #14085
This commit is contained in:
Manlio Perillo 2023-06-17 22:35:50 +02:00 committed by GitHub
parent 6e84f46990
commit 366e3c657f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 58 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
doc/langref.html.in
View File

@ -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#}.