From 2ead606cb57c02bb6c67fc5c0d711bb163328627 Mon Sep 17 00:00:00 2001
From: Bryan Lee <38807139+liby@users.noreply.github.com>
Date: Mon, 13 Jan 2025 00:20:28 +0800
Subject: [PATCH] Improve `list-actions` command documentation formatting

This commit fixes two issues with the `list-actions` command:

1. Ensures all actions are listed, including those without individual
   documentation but sharing docs with related actions
2. Improves documentation formatting with proper indentation and grouping
---
 src/cli/list_actions.zig | 48 +++++++++++++++++++++++++++++++---------
 src/helpgen.zig          | 34 +---------------------------
 2 files changed, 39 insertions(+), 43 deletions(-)

diff --git a/src/cli/list_actions.zig b/src/cli/list_actions.zig
index 65b9dcdadc..e4b22023d2 100644
--- a/src/cli/list_actions.zig
+++ b/src/cli/list_actions.zig
@@ -3,6 +3,7 @@ const args = @import("args.zig");
 const Action = @import("action.zig").Action;
 const Allocator = std.mem.Allocator;
 const help_strings = @import("help_strings");
+const KeybindAction = @import("../input/Binding.zig").Action;
 
 pub const Options = struct {
     /// If `true`, print out documentation about the action associated with the
@@ -36,19 +37,46 @@ pub fn run(alloc: Allocator) !u8 {
     }
 
     const stdout = std.io.getStdOut().writer();
-    const info = @typeInfo(help_strings.KeybindAction);
-    inline for (info.Struct.decls) |field| {
-        try stdout.print("{s}", .{field.name});
-        if (opts.docs) {
-            try stdout.print(":\n", .{});
-            var iter = std.mem.splitScalar(u8, std.mem.trimRight(u8, @field(help_strings.KeybindAction, field.name), &std.ascii.whitespace), '\n');
-            while (iter.next()) |line| {
-                try stdout.print("  {s}\n", .{line});
+
+    var buffer = std.ArrayList(u8).init(std.heap.page_allocator);
+    defer buffer.deinit();
+
+    const fields = @typeInfo(KeybindAction).Union.fields;
+    inline for (fields) |field| {
+        if (field.name[0] == '_') continue;
+
+        // Write previously stored doc comment below all related actions
+        if (@hasDecl(help_strings.KeybindAction, field.name)) {
+            try stdout.writeAll(buffer.items);
+            try stdout.writeAll("\n");
+
+            buffer.clearRetainingCapacity();
+        }
+
+        // Write the field name.
+        try stdout.writeAll(field.name);
+        try stdout.writeAll(":\n");
+
+        if (@hasDecl(help_strings.KeybindAction, field.name)) {
+            var iter = std.mem.splitScalar(
+                u8,
+                @field(help_strings.KeybindAction, field.name),
+                '\n',
+            );
+            while (iter.next()) |s| {
+                // If it is the last line and empty, then skip it.
+                if (iter.peek() == null and s.len == 0) continue;
+                try buffer.appendSlice("  ");
+                try buffer.appendSlice(s);
+                try buffer.appendSlice("\n");
             }
-        } else {
-            try stdout.print("\n", .{});
         }
     }
 
+    // Write any remaining buffered documentation
+    if (buffer.items.len > 0) {
+        try stdout.writeAll(buffer.items);
+    }
+
     return 0;
 }
diff --git a/src/helpgen.zig b/src/helpgen.zig
index 646f7fd47f..2084fb9f7e 100644
--- a/src/helpgen.zig
+++ b/src/helpgen.zig
@@ -115,38 +115,6 @@ fn genActions(alloc: std.mem.Allocator, writer: anytype) !void {
     try writer.writeAll("};\n");
 }
 
-fn genKeybindField(
-    alloc: std.mem.Allocator,
-    writer: anytype,
-    ast: std.zig.Ast,
-    comptime field: []const u8,
-) !void {
-    const tokens = ast.tokens.items(.tag);
-
-    // Find the field and check if it has doc comments
-    for (tokens, 0..) |token, i| {
-        if (token != .identifier) continue;
-        const name = ast.tokenSlice(@intCast(i));
-        if (!std.mem.eql(u8, name, field)) continue;
-
-        try writer.writeAll("pub const ");
-        try writer.writeAll(name);
-        try writer.writeAll(": [:0]const u8 = \n");
-
-        // If it has doc comments, use them
-        if (i > 0 and tokens[i - 1] == .doc_comment) {
-            const comment = try extractDocComments(alloc, ast, @intCast(i - 1), tokens);
-            try writer.writeAll(comment);
-        } else {
-            // Otherwise use default documentation
-            try writer.writeAll("    \\\\This action is currently undocumented.\n");
-            try writer.writeAll("    \\\\Please refer to the source code or contribute documentation.\n");
-            try writer.writeAll(";\n");
-        }
-        break;
-    }
-}
-
 fn genKeybindActions(alloc: std.mem.Allocator, writer: anytype) !void {
     var ast = try std.zig.Ast.parse(alloc, @embedFile("input/Binding.zig"), .zig);
     defer ast.deinit(alloc);
@@ -160,7 +128,7 @@ fn genKeybindActions(alloc: std.mem.Allocator, writer: anytype) !void {
 
     inline for (@typeInfo(KeybindAction).Union.fields) |field| {
         if (field.name[0] == '_') continue;
-        try genKeybindField(alloc, writer, ast, field.name);
+        try genConfigField(alloc, writer, ast, field.name);
     }
 
     try writer.writeAll("};\n");