authorgravatar for manlio.perillo@gmail.comManlio Perillo <manlio.perillo@gmail.com> 2023-06-17 22:35:50+02:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2023-06-17 16:35:50-04:00
log366e3c657fe7d898465a0e822f1999f0572f832e
tree51e5f36f48d9d9612b71236526c2328b515ddf8c
parent6e84f469904a24615a6721265a88ad8dcb4ed83a
signaturebadge-question-mark Signed by PGP key 4AEE18F83AFDEB23

Langref misc fix and improvement (#14695)

* 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

1 files changed, 58 insertions(+), 17 deletions(-)

doc/langref.html.in+58-17
......@@ -413,7 +413,7 @@ pub fn main() !void {
413413 <p>
414414 The code sample shows the contents of a file named <code class="file">hello.zig</code>. Files storing Zig
415415 source code are {#link|UTF-8 encoded|Source Encoding#} text files. The files storing
416 Zig source code are usually named with the <code class="file"><em>.zig</em></code> extension.
416 Zig source code must be named with the <code class="file"><em>.zig</em></code> extension.
417417 </p>
418418 <p>
419419 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 {
487487 purposely written to show how to perform {#link|string|String Literals and Unicode Code Point Literals#}
488488 substitution in the {#syntax#}print{#endsyntax#} function. The curly-braces inside of the first argument
489489 are substituted with the compile-time known value inside of the second argument
490 (known as an {#link|tuple|Tuples#}). The <code>\n</code>
490 (known as a {#link|tuple|Tuples#}). The <code>\n</code>
491491 inside of the double-quotes of the first argument is the {#link|escape sequence|Escape Sequences#} for the
492492 newline character. The {#link|try#} expression evaluates the result of {#syntax#}stdout.print{#endsyntax#}.
493493 If the result is an error, then the {#syntax#}try{#endsyntax#} expression will return from
......@@ -518,6 +518,14 @@ pub fn main() void {
518518 {#see_also|Values|@import|Errors|Root Source File|Source Encoding#}
519519 {#header_close#}
520520 {#header_open|Comments#}
521 <p>
522 Zig supports 3 types of comments. Normal comments are ignored, but doc comments
523 and top-level doc comments are used by the compiler to generate the package documentation.
524 </p>
525 <p>
526 The generated documentation is still experimental, and can be produced with:
527 </p>
528 {#shell_samp#}zig test -femit-docs main.zig{#end_shell_samp#}
521529 {#code_begin|exe|comments#}
522530const print = @import("std").debug.print;
523531
......@@ -535,7 +543,7 @@ pub fn main() void {
535543 comments in C). This helps allow Zig to have the property that each line
536544 of code can be tokenized out of context.
537545 </p>
538 {#header_open|Doc comments#}
546 {#header_open|Doc Comments#}
539547 <p>
540548 A doc comment is one that begins with exactly three slashes (i.e.
541549 {#syntax#}///{#endsyntax#} but not {#syntax#}////{#endsyntax#});
......@@ -562,21 +570,44 @@ const Timestamp = struct {
562570};
563571 {#code_end#}
564572 <p>
565 Doc comments are only allowed in certain places; eventually, it will
566 become a compile error to have a doc comment in an unexpected place, such as
567 in the middle of an expression, or just before a non-doc comment.
573 Doc comments are only allowed in certain places; it is a compile error to
574 have a doc comment in an unexpected place, such as in the middle of an expression,
575 or just before a non-doc comment.
576 </p>
577 {#code_begin|obj_err|invalid_doc-comment|expected type expression, found 'a document comment'#}
578/// doc-comment
579//! top-level doc-comment
580const std = @import("std");
581 {#code_end#}
582 {#code_begin|obj_err|unattached_doc-comment|unattached documentation comment#}
583pub fn main() void {}
584
585/// End of file
586 {#code_end#}
587 <p>
588 Doc comments can be interleaved with normal comments. Currently, when producing
589 the package documentation, normal comments are merged with doc comments.
568590 </p>
569591 {#header_close#}
570592 {#header_open|Top-Level Doc Comments#}
571 <p>User documentation that doesn't belong to whatever
572 immediately follows it, like {#link|container|Containers#}-level documentation, goes
573 in top-level doc comments. A top-level doc comment is one that
574 begins with two slashes and an exclamation point:
575 {#syntax#}//!{#endsyntax#}.</p>
593 <p>
594 A top-level doc comment is one that begins with two slashes and an exclamation
595 point: {#syntax#}//!{#endsyntax#}; it documents the current module.
596 </p>
597 <p>
598 It is a compile error if a top-level doc comment is not placed at the start
599 of a {#link|container|Containers#}, before any expressions.
600 </p>
576601 {#code_begin|syntax|tldoc_comments#}
577602//! This module provides functions for retrieving the current date and
578603//! time with varying degrees of precision and accuracy. It does not
579604//! depend on libc, but will use functions from it if available.
605
606const S = struct {
607 //! Top level comments are allowed inside a container other than a module,
608 //! but it is not very useful. Currently, when producing the package
609 //! documentation, these comments are ignored.
610};
580611 {#code_end#}
581612 {#header_close#}
582613 {#header_close#}
......@@ -1060,6 +1091,11 @@ test "expect addOne adds one to 41" {
10601091 try std.testing.expect(addOne(41) == 42);
10611092}
10621093
1094test addOne {
1095 // A test name can also be written using an identifier.
1096 try std.testing.expect(addOne(41) == 42);
1097}
1098
10631099/// The function `addOne` adds one to the number given as its argument.
10641100fn addOne(number: i32) i32 {
10651101 return number + 1;
......@@ -1087,20 +1123,25 @@ fn addOne(number: i32) i32 {
10871123 printed to standard error by the default test runner:
10881124 </p>
10891125 <dl>
1090 <dt><samp>Test [1/1] test "expect addOne adds one to 41"...</samp></dt>
1126 <dt><samp>Test [1/2] test.expect addOne adds one to 41...</samp></dt>
10911127 <dd>Lines like this indicate which test, out of the total number of tests, is being run.
1092 In this case, <samp>[1/1]</samp> indicates that the first test, out of a total of
1093 one test, is being run. Note that, when the test runner program's standard error is output
1128 In this case, <samp>[1/2]</samp> indicates that the first test, out of a total of
1129 two test, is being run. Note that, when the test runner program's standard error is output
10941130 to the terminal, these lines are cleared when a test succeeds.
10951131 </dd>
1096 <dt><samp>All 1 tests passed.</samp></dt>
1132 <dt><samp>Test [2/2] decltest.addOne...</samp></dt>
1133 <dd>When the test name is an identifier, the default test runner uses the text
1134 decltest instead of test.
1135 </dd>
1136 <dt><samp>All 2 tests passed.</samp></dt>
10971137 <dd>This line indicates the total number of tests that have passed.</dd>
10981138 </dl>
10991139 {#header_open|Test Declarations#}
11001140 <p>
11011141 Test declarations contain the {#link|keyword|Keyword Reference#} {#syntax#}test{#endsyntax#}, followed by an
1102 optional name written as a {#link|string literal|String Literals and Unicode Code Point Literals#}, followed
1103 by a {#link|block|Blocks#} containing any valid Zig code that is allowed in a {#link|function|Functions#}.
1142 optional name written as a {#link|string literal|String Literals and Unicode Code Point Literals#} or an
1143 {#link|identifier|Identifiers#}, followed by a {#link|block|Blocks#} containing any valid Zig code that
1144 is allowed in a {#link|function|Functions#}.
11041145 </p>
11051146 <aside>
11061147 By convention, non-named tests should only be used to {#link|make other tests run|Nested Container Tests#}.