Comments

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.

The generated documentation is still experimental, and can be produced with:

Shell

  1. zig test -femit-docs main.zig

comments.zig

  1. const print = @import("std").debug.print;
  3. pub fn main() void {
  4.     // Comments in Zig start with "//" and end at the next LF byte (end of line).
  5.     // The line below is a comment and won't be executed.
  7.     //print("Hello?", .{});
  9.     print("Hello, world!\n", .{}); // another comment
  10. }

Shell

  1. $ zig build-exe comments.zig
  2. $ ./comments
  3. Hello, world!

There are no multiline comments in Zig (e.g. like /* */ comments in C). This allows Zig to have the property that each line of code can be tokenized out of context.

Doc Comments

A doc comment is one that begins with exactly three slashes (i.e. /// but not ////); multiple doc comments in a row are merged together to form a multiline doc comment. The doc comment documents whatever immediately follows it.

doc_comments.zig

  1. /// A structure for storing a timestamp, with nanosecond precision (this is a
  2. /// multiline doc comment).
  3. const Timestamp = struct {
  4.     /// The number of seconds since the epoch (this is also a doc comment).
  5.     seconds: i64,  // signed so we can represent pre-1970 (not a doc comment)
  6.     /// The number of nanoseconds past the second (doc comment again).
  7.     nanos: u32,
  9.     /// Returns a `Timestamp` struct representing the Unix epoch; that is, the
  10.     /// moment of 1970 Jan 1 00:00:00 UTC (this is a doc comment too).
  11.     pub fn unixEpoch() Timestamp {
  12.         return Timestamp{
  13.             .seconds = 0,
  14.             .nanos = 0,
  15.         };
  16.     }
  17. };

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.

invalid_doc-comment.zig

  1. /// doc-comment
  2. //! top-level doc-comment
  3. const std = @import("std");

Shell

  1. $ zig build-obj invalid_doc-comment.zig
  2. docgen_tmp/invalid_doc-comment.zig:1:16: error: expected type expression, found 'a document comment'
  3. /// doc-comment
  4.                ^

unattached_doc-comment.zig

  1. pub fn main() void {}
  3. /// End of file

Shell

  1. $ zig build-obj unattached_doc-comment.zig
  2. docgen_tmp/unattached_doc-comment.zig:3:1: error: unattached documentation comment
  3. /// End of file
  4. ^~~~~~~~~~~~~~~

Doc comments can be interleaved with normal comments. Currently, when producing the package documentation, normal comments are merged with doc comments.

Top-Level Doc Comments

A top-level doc comment is one that begins with two slashes and an exclamation point: //!; it documents the current module.

It is a compile error if a top-level doc comment is not placed at the start of a container, before any expressions.

tldoc_comments.zig

  1. //! This module provides functions for retrieving the current date and
  2. //! time with varying degrees of precision and accuracy. It does not
  3. //! depend on libc, but will use functions from it if available.
  5. const S = struct {
  6.     //! Top level comments are allowed inside a container other than a module,
  7.     //! but it is not very useful.  Currently, when producing the package
  8.     //! documentation, these comments are ignored.
  9. };