From ee8d0cde34b012e58699d4ae2b57c00313f2352a Mon Sep 17 00:00:00 2001
From: falsycat <me@falsy.cat>
Date: Wed, 2 Apr 2025 22:52:13 +0900
Subject: [PATCH] improve doc comments

---
 build.zig              |  9 +++++++++
 src/hncore/Digraph.zig | 21 ++++++++++++++++-----
 src/hncore/Node.zig    |  6 +++++-
 src/hncore/Store.zig   | 19 ++++++++++++++-----
 4 files changed, 44 insertions(+), 11 deletions(-)

diff --git a/build.zig b/build.zig
index 09916ba..3085c3b 100644
--- a/build.zig
+++ b/build.zig
@@ -59,4 +59,13 @@ pub fn build(b: *std.Build) void {
 
     const test_step = b.step("test", "Run unit tests");
     test_step.dependOn(&run_lib_unit_tests.step);
+
+    // ---- document generation
+    const install_docs = b.addInstallDirectory(.{
+        .source_dir     = lib.getEmittedDocs(),
+        .install_dir    = .prefix,
+        .install_subdir = "docs",
+    });
+    const docs_step = b.step("docs", "Install docs into zig-out/docs");
+    docs_step.dependOn(&install_docs.step);
 }
diff --git a/src/hncore/Digraph.zig b/src/hncore/Digraph.zig
index 44ec4df..b1da362 100644
--- a/src/hncore/Digraph.zig
+++ b/src/hncore/Digraph.zig
@@ -3,14 +3,23 @@ const std = @import("std");
 /// A data type to store connections of nodes in directional-graph.
 pub fn Digraph(comptime T: type, comptime lessThanFn: LessThanFunc(T)) type {
     return struct {
-        const Node     = T;
-        const Conn     = struct { from: T, to: T, };
+        ///
+        const Node = T;
+
+        /// A connection between 2 nodes.
+        /// e.g.) `Conn { .from = X, .to = Y }` =>  "X is connected to Y"
+        const Conn = struct { from: T, to: T, };
+
+        ///
         const ConnList = std.ArrayList(Conn);
-        const Error    = error {
+
+        ///
+        const Error = error {
             AlreadyConnected,
             NotConnected,
         };
 
+        ///
         map: ConnList,
 
         ///
@@ -31,7 +40,8 @@ pub fn Digraph(comptime T: type, comptime lessThanFn: LessThanFunc(T)) type {
             self.map.deinit();
         }
 
-        ///
+        /// Makes new connection between `from` to `to`.
+        /// Returns false if they are already connected otherwise true.
         pub fn connectIf(self: *@This(), from: T, to: T) !bool {
             const begin, const end = self.findSegment(from);
             if (self.findConnectionInSegment(from, to, begin, end)) |_| {
@@ -48,7 +58,8 @@ pub fn Digraph(comptime T: type, comptime lessThanFn: LessThanFunc(T)) type {
             }
         }
 
-        ///
+        /// Removes an existing connection between `from` to `to`.
+        /// Returns false if they are not connected otherwise true.
         pub fn disconnectIf(self: *@This(), from: T, to: T) bool {
             const begin, const end = self.findSegment(from);
             if (self.findConnectionInSegment(from, to, begin, end)) |idx| {
diff --git a/src/hncore/Node.zig b/src/hncore/Node.zig
index 2f19868..75b58a7 100644
--- a/src/hncore/Node.zig
+++ b/src/hncore/Node.zig
@@ -1,7 +1,11 @@
 const std = @import("std");
 
+///
 pub const Node = struct {
-    id     : usize,
+    /// unique and immutable integer
+    id: usize,
+
+    /// summary text of this node
     summary: []const u8,
 
     ///
diff --git a/src/hncore/Store.zig b/src/hncore/Store.zig
index 5315708..3d168ce 100644
--- a/src/hncore/Store.zig
+++ b/src/hncore/Store.zig
@@ -8,7 +8,10 @@ pub fn Store(comptime T: type) type {
         deinitItem: ?*fn (?*anyopaque, *T) void = null,
     };
     return struct {
+        ///
         const Item = T;
+
+        /// A struct which holds an item and its reference count.
         const Slot = struct {
             item  : Item,
             refcnt: usize,
@@ -20,21 +23,27 @@ pub fn Store(comptime T: type) type {
                 self.refcnt -= 1;
             }
         };
-        const Slots = std.ArrayList(*Slot);
+
+        ///
         const Error = error {
             DetectedItemLeak,
         };
 
+        ///
         alloc : std.mem.Allocator,
+
+        ///
         vtable: VTable,
-        slots : Slots,
+
+        ///
+        slots : std.ArrayList(Slot),
 
         ///
         pub fn init(alloc: std.mem.Allocator, vtable: VTable) @This() {
             return .{
                 .alloc  = alloc,
                 .vtable = vtable,
-                .slots  = Slots.init(alloc),
+                .slots  = std.ArrayList(Slot).init(alloc),
             };
         }
         ///
@@ -48,7 +57,7 @@ pub fn Store(comptime T: type) type {
         }
 
         /// Returns a slot which contains newly-allocated item.
-        /// - A reference count of the returned slot must be 1
+        /// - A reference count of the returned slot is 1
         /// - The returned slot and its contents are alive till the reference count becomes 0
         pub fn add(self: *@This(), item: Item) !*Slot {
             for (self.slots.items) |slot| {
@@ -68,7 +77,7 @@ pub fn Store(comptime T: type) type {
         }
 
         /// Releases memory of slots whose reference count is 0.
-        /// Usually no need to call this function because such slots are reused.
+        /// Usually no need to call this function because such slots will be reused.
         pub fn collectGarbage(self: *@This()) !void {
             var slots = self.slots.items;