コメント（// と ///）

// 一行コメント — // から行末までがコメントになります。
const x: i32 = 10; // 行末コメント — コードの後にも書けます。

/// ドキュメントコメント — 直後の宣言（関数・型・定数等）を文書化します。
/// 複数行書く場合は各行に /// を付けます。
/// 自動ドキュメントツールが解析して HTML 等を生成します。
pub fn exampleFunction() void {}

Zigにはブロックコメント（『/* */』）はありません。複数行コメントを書く場合は各行に『//』または『///』を付けます。

『///』で始まるドキュメントコメントは直後の宣言に関連付けられ、ビルドシステムの自動ドキュメント生成機能で利用されます。Zigの公式ドキュメント（docs.ziglang.org の標準ライブラリリファレンス）もこの仕組みで生成されています。

ドキュメントコメントとして認識されるには、コメントと宣言の間に空行を挟まないことが必要です。

コメントの書き方（一行・ドキュメントコメント）を確認するサンプルコードです。

comment_basic.zig

// comment_basic.zig — Zig のコメント構文の基本的な使い方です。

const std = @import("std");

// 商品数を定数として定義します
const item_count = 3;

pub fn main() void {
    // 商品名と価格の配列を定義します
    const items = [item_count][]const u8{ "widget", "gadget", "device" };
    const prices = [item_count]i32{ 1200, 3500, 800 }; // 税抜価格

    var total: i32 = 0;

    for (0..item_count) |i| {
        std.debug.print("{s:<10} {d:>5} yen\n", .{ items[i], prices[i] });
        total += prices[i];
    }

    std.debug.print("----------\n", .{});
    std.debug.print("{s:<10} {d:>5} yen\n", .{ "Total", total });
}

$ zig run comment_basic.zig
widget      1200 yen
gadget      3500 yen
device       800 yen
----------
Total       5500 yen

comment_doc.zig

// comment_doc.zig — /// ドキュメントコメントの使い方です。

const std = @import("std");

/// 整数スライスの合計値を計算して返します。
///
/// 引数:
///   values — 合計を計算する i32 スライス
///
/// 戻り値:
///   全要素の合計値（i32）
pub fn sum(values: []const i32) i32 {
    var total: i32 = 0;
    for (values) |v| {
        total += v;
    }
    return total;
}

/// 整数スライスの平均値を計算して返します。
///
/// スライスが空の場合は null を返します。
///
/// 引数:
///   values — 平均を計算する i32 スライス
///
/// 戻り値:
///   平均値（f64）。スライスが空の場合は null。
pub fn average(values: []const i32) ?f64 {
    if (values.len == 0) {
        // 空スライスは計算不能なので null を返します
        return null;
    }

    // 整数除算を避けるため f64 にキャストします
    return @as(f64, @floatFromInt(sum(values))) / @as(f64, @floatFromInt(values.len));
}

pub fn main() void {
    const scores = [_]i32{ 85, 92, 78, 95, 60 };

    std.debug.print("Sum:     {d}\n", .{sum(&scores)});

    if (average(&scores)) |avg| {
        std.debug.print("Average: {d:.1}\n", .{avg});
    }

    // 空スライスのケース
    const empty = [_]i32{};
    const result = average(&empty);
    std.debug.print("Empty:   {any}\n", .{result});
}

$ zig run comment_doc.zig
Sum:     410
Average: 82.0
Empty:   null

ドキュメントコメントと宣言の間に空行を入れる

『///』と宣言の間に空行があると、ドキュメントコメントとして認識されません。コンパイルエラーにはなりませんが、自動ドキュメントに反映されなくなります。

/// この関数を説明します。（ドキュメントとして認識されません）

pub fn example() void {} // 空行があるため /// がドキュメントに結びつかない

ブロックコメントを書こうとする

Zigには『/* */』というブロックコメントはありません。複数行コメントを書く場合は各行の先頭に『//』または『///』を付けます。

/* これはコンパイルエラーになります */ // NG: Zig にブロックコメントはない

// これが Zig の複数行コメントの正しい書き方です。
// 各行に // を付けます。

Zigのコメントは『//』による一行コメントと、ドキュメントコメントとしての『///』の2種類です。Zigには『/* */』のようなブロックコメントは存在しません。複数行にわたるコメントを書く場合は各行に『//』または『///』を付けます。

『///』ドキュメントコメントは直後の宣言に紐づき、自動ドキュメント生成ツールが解析します。Zigの公式標準ライブラリドキュメントもこの仕組みで生成されています。エクスポートされた宣言（pub）には『///』でドキュメントコメントを付けるのが慣習で、内部実装には通常の『//』を使います。コメントと宣言の間に空行を挟まないことが重要です。