Add "Comments" section to language reference (#1309)

The contents of this section come from the discussion on issue #1305.

1 files changed, 52 insertions, 0 deletions

diff --git a/doc/langref.html.in b/doc/langref.html.in
index 0499c632e2..7fde550338 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -134,6 +134,58 @@ pub fn main() void {
       </p>
       {#see_also|Values|@import|Errors|Root Source File#}
       {#header_close#}
+      {#header_open|Comments#}
+      {#code_begin|test|comments#}
+const assert = @import("std").debug.assert;
+
+test "comments" {
+    // Comments in Zig start with "//" and end at the next LF byte (end of line).
+    // The below line is a comment, and won't be executed.
+
+    //assert(false);
+
+    const x = true;  // another comment
+    assert(x);
+}
+      {#code_end#}
+      <p>
+      There are no multiline comments in Zig (e.g. like <code>/* */</code>
+      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#}
+      <p>
+      A doc comment is one that begins with exactly three slashes (i.e.
+      <code class="zig">///</code> but not <code class="zig">////</code>);
+      multiple doc comments in a row are merged together to form a multiline
+      doc comment.  The doc comment documents whatever immediately follows it.
+      </p>
+      {#code_begin|syntax|doc_comments#}
+/// A structure for storing a timestamp, with nanosecond precision (this is a
+/// multiline doc comment).
+const Timestamp = struct {
+    /// The number of seconds since the epoch (this is also a doc comment).
+    seconds: i64,  // signed so we can represent pre-1970 (not a doc comment)
+    /// The number of nanoseconds past the second (doc comment again).
+    nanos: u32,
+
+    /// Returns a `Timestamp` struct representing the Unix epoch; that is, the
+    /// moment of 1970 Jan 1 00:00:00 UTC (this is a doc comment too).
+    pub fn unixEpoch() Timestamp {
+        return Timestamp{
+            .seconds = 0,
+            .nanos = 0,
+        };
+    }
+};
+      {#code_end#}
+      <p>
+      Doc comments are only allowed in certain places; eventually, it will
+      become a compile error have a doc comment in an unexpected place, such as
+      in the middle of an expression, or just before a non-doc comment.
+      </p>
+      {#header_close#}
+      {#header_close#}
       {#header_open|Values#}
       {#code_begin|exe|values#}
 const std = @import("std");