Commit 366e3c657fe7d898465a0e822f1999f0572f832e | zig

author	Manlio Perillo <manlio.perillo@gmail.com> 2023-06-17 22:35:50+02:00
committer	GitHub <noreply@github.com> 2023-06-17 16:35:50-04:00
log	366e3c657fe7d898465a0e822f1999f0572f832e
tree	51e5f36f48d9d9612b71236526c2328b515ddf8c
parent	6e84f469904a24615a6721265a88ad8dcb4ed83a
signature	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

doc/langref.html.in+58-17

 @@ -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
+      Doc comments are only allowed in certain places; it is a compile error to
-      become a compile error to have a doc comment in an unexpected place, such as
+      have a doc comment in an unexpected place, such as in the middle of an expression,
-      in the middle of an expression, or just before a non-doc comment.
+      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
+      <p>
-      immediately follows it, like {#link|container|Containers#}-level documentation, goes
+      A top-level doc comment is one that begins with two slashes and an exclamation
-      in top-level doc comments. A top-level doc comment is one that
+      point: {#syntax#}//!{#endsyntax#}; it documents the current module.
-      begins with two slashes and an exclamation point:
+      </p>
-      {#syntax#}//!{#endsyntax#}.</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
+          In this case, <samp>[1/2]</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
+          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
+        optional name written as a {#link|string literal|String Literals and Unicode Code Point Literals#} or an
-        by a {#link|block|Blocks#} containing any valid Zig code that is allowed in a {#link|function|Functions#}.
+        {#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#}.