From a76803aad1dcedb8a8ceab1d0f9e4faa6dfac4d7 Mon Sep 17 00:00:00 2001
From: "Caleb J. Gardner" <calebq23@gmail.com>
Date: Sat, 31 Jan 2026 05:14:00 -0600
Subject: [PATCH] Comments!

---
 src/decomp.zig           |  2 ++
 src/dir_entry.zig        |  2 ++
 src/file.zig             | 24 +++++++++++++++++++++---
 src/inode.zig            |  2 ++
 src/inode_data/misc.zig  |  4 ++++
 src/options.zig          |  2 ++
 src/table.zig            |  1 +
 src/util/data.zig        |  2 ++
 src/util/offset_file.zig |  2 +-
 9 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/src/decomp.zig b/src/decomp.zig
index 8b8241d..e56ccdd 100644
--- a/src/decomp.zig
+++ b/src/decomp.zig
@@ -1,3 +1,5 @@
+//! Decompression manager. Can decompress either from an Io.Reader or from a byte slice.
+
 const std = @import("std");
 const compress = std.compress;
 const Reader = std.Io.Reader;
diff --git a/src/dir_entry.zig b/src/dir_entry.zig
index c3dd882..3e4bcaa 100644
--- a/src/dir_entry.zig
+++ b/src/dir_entry.zig
@@ -1,3 +1,5 @@
+//! Directory entry from the directory table.
+
 const std = @import("std");
 const Reader = std.Io.Reader;
 
diff --git a/src/file.zig b/src/file.zig
index e90ec4c..b046b45 100644
--- a/src/file.zig
+++ b/src/file.zig
@@ -1,3 +1,5 @@
+//! A file/directory within the squashfs archive.
+
 const std = @import("std");
 const File = std.fs.File;
 const WaitGroup = std.Thread.WaitGroup;
@@ -391,9 +393,25 @@ fn extractReal(self: SfsFile, path: []const u8, options: ExtractionOptions, pol:
             };
         },
         .dir, .ext_dir => {
-            _ = std.fs.cwd().statFile(path) catch |err| {
-                if (err == error.FileNotFound) {}
-            };
+            if (std.fs.cwd().statFile(path)) |stat| {
+                if (stat.kind != .directory) {
+                    std.log.err("{s} exists and is not a folder\n", .{path});
+                    out_err.* = FileError.ExtractionPathExists;
+                    return;
+                }
+            } else |err| {
+                if (err == error.FileNotFound) {
+                    std.fs.cwd().makeDir(path) catch |err_2| {
+                        std.log.err("Error creating {s}: {}\n", .{ path, err_2 });
+                        out_err.* = err;
+                        return;
+                    };
+                } else {
+                    std.log.err("Error checking if {s} exists: {}\n", .{ path, err });
+                    out_err.* = err;
+                    return;
+                }
+            }
             var dir_wg: *WaitGroup = self.archive.allocator().create(WaitGroup) catch |err| {
                 std.log.err("Error allocating waitgroup for {s} (inode {}): {}\n", .{ path, self.inode.hdr.num, err });
                 out_err.* = err;
diff --git a/src/inode.zig b/src/inode.zig
index cd5407e..48f7deb 100644
--- a/src/inode.zig
+++ b/src/inode.zig
@@ -1,3 +1,5 @@
+//! A file-system object. Represents a File or directory.
+
 const std = @import("std");
 const Reader = std.Io.Reader;
 
diff --git a/src/inode_data/misc.zig b/src/inode_data/misc.zig
index 2a5417f..d18a837 100644
--- a/src/inode_data/misc.zig
+++ b/src/inode_data/misc.zig
@@ -49,6 +49,7 @@ pub const ExtSymlink = struct {
     }
 };
 
+/// A block or character device.
 pub const Dev = packed struct {
     hard_links: u32,
     dev: u32,
@@ -60,6 +61,7 @@ pub const Dev = packed struct {
     }
 };
 
+/// An extended block or character device.
 pub const ExtDev = packed struct {
     hard_links: u32,
     dev: u32,
@@ -72,6 +74,7 @@ pub const ExtDev = packed struct {
     }
 };
 
+/// A socket or FIFO file.
 pub const IPC = packed struct {
     hard_links: u32,
 
@@ -82,6 +85,7 @@ pub const IPC = packed struct {
     }
 };
 
+/// An extended socket or FIFO file.
 pub const ExtIPC = packed struct {
     hard_links: u32,
     xattr_idx: u32,
diff --git a/src/options.zig b/src/options.zig
index f89c29f..16402cf 100644
--- a/src/options.zig
+++ b/src/options.zig
@@ -1,3 +1,5 @@
+//! Options for file/directory extraction.
+
 const std = @import("std");
 const Writer = std.Io.Writer;
 
diff --git a/src/table.zig b/src/table.zig
index 693cbf8..51c16b4 100644
--- a/src/table.zig
+++ b/src/table.zig
@@ -9,6 +9,7 @@ const TableError = error{
     InvalidIndex,
 };
 
+/// A two-layer metadata table.
 pub fn Table(T: anytype) type {
     return struct {
         const Self = @This();
diff --git a/src/util/data.zig b/src/util/data.zig
index 3b4bf7e..59ccf26 100644
--- a/src/util/data.zig
+++ b/src/util/data.zig
@@ -1,3 +1,5 @@
+//! A reader for a regular file.
+
 const std = @import("std");
 const Reader = std.Io.Reader;
 const Writer = std.Io.Writer;
diff --git a/src/util/offset_file.zig b/src/util/offset_file.zig
index 8ba8be7..b03c1b2 100644
--- a/src/util/offset_file.zig
+++ b/src/util/offset_file.zig
@@ -1,4 +1,4 @@
-//! A File that's meant where it's meaningful content starts at a given offset.
+//! A File where it's meaningful (to us) content starts at a given offset.
 
 const std = @import("std");
 const File = std.fs.File;