From e21b94696842516b71ff93b4c0b5edae53efecff Mon Sep 17 00:00:00 2001
From: Derek Miller <derek@finitelabs.com>
Date: Tue, 27 Jan 2026 12:01:23 -0600
Subject: [PATCH] Add type annotations and class definitions to all bitn
 modules for improved documentation and tooling

---
 src/bitn/_compat.lua         | 2 ++
 src/bitn/bit16.lua           | 1 +
 src/bitn/bit32.lua           | 1 +
 src/bitn/bit64.lua           | 1 +
 src/bitn/init.lua            | 4 ++++
 src/bitn/utils/benchmark.lua | 1 +
 src/bitn/utils/init.lua      | 2 ++
 7 files changed, 12 insertions(+)

diff --git a/src/bitn/_compat.lua b/src/bitn/_compat.lua
index ccbd1d6..917b6df 100644
--- a/src/bitn/_compat.lua
+++ b/src/bitn/_compat.lua
@@ -1,6 +1,8 @@
+--- @diagnostic disable: duplicate-set-field
 --- @module "bitn._compat"
 --- Internal compatibility layer for bitwise operations.
 --- Provides feature detection and optimized primitives for use by bit16/bit32/bit64.
+--- @class bitn._compat
 local _compat = {}
 
 --------------------------------------------------------------------------------
diff --git a/src/bitn/bit16.lua b/src/bitn/bit16.lua
index 842a05c..d912a15 100644
--- a/src/bitn/bit16.lua
+++ b/src/bitn/bit16.lua
@@ -3,6 +3,7 @@
 --- This module provides a complete, version-agnostic implementation of 16-bit
 --- bitwise operations that works across Lua 5.1, 5.2, 5.3, 5.4, and LuaJIT.
 --- Uses native bit operations where available for optimal performance.
+--- @class bitn.bit16
 local bit16 = {}
 
 local _compat = require("bitn._compat")
diff --git a/src/bitn/bit32.lua b/src/bitn/bit32.lua
index 2c0a83b..7e04187 100644
--- a/src/bitn/bit32.lua
+++ b/src/bitn/bit32.lua
@@ -3,6 +3,7 @@
 --- This module provides a complete, version-agnostic implementation of 32-bit
 --- bitwise operations that works across Lua 5.1, 5.2, 5.3, 5.4, and LuaJIT.
 --- Uses native bit operations where available for optimal performance.
+--- @class bitn.bit32
 local bit32 = {}
 
 local _compat = require("bitn._compat")
diff --git a/src/bitn/bit64.lua b/src/bitn/bit64.lua
index 066063d..c7021ad 100644
--- a/src/bitn/bit64.lua
+++ b/src/bitn/bit64.lua
@@ -4,6 +4,7 @@
 --- where high is the upper 32 bits and low is the lower 32 bits.
 --- Works across Lua 5.1, 5.2, 5.3, 5.4, and LuaJIT.
 --- Uses native bit operations where available for optimal performance.
+--- @class bitn.bit64
 local bit64 = {}
 
 local bit32 = require("bitn.bit32")
diff --git a/src/bitn/init.lua b/src/bitn/init.lua
index 214300b..736dcbd 100644
--- a/src/bitn/init.lua
+++ b/src/bitn/init.lua
@@ -18,9 +18,13 @@
 --- -- 16-bit operations
 --- local shifted = bitn.bit16.lshift(1, 8)  -- 256
 ---
+--- @class bitn
 local bitn = {
+  --- @type bitn.bit16 16-bit bitwise operations
   bit16 = require("bitn.bit16"),
+  --- @type bitn.bit32 32-bit bitwise operations
   bit32 = require("bitn.bit32"),
+  --- @type bitn.bit64 64-bit bitwise operations
   bit64 = require("bitn.bit64"),
 }
 
diff --git a/src/bitn/utils/benchmark.lua b/src/bitn/utils/benchmark.lua
index e813bef..41075ed 100644
--- a/src/bitn/utils/benchmark.lua
+++ b/src/bitn/utils/benchmark.lua
@@ -1,5 +1,6 @@
 --- @module "bitn.utils.benchmark"
 --- Common benchmarking utilities for performance testing
+--- @class bitn.utils.benchmark
 local benchmark = {}
 
 --- Run a benchmarked operation with warmup and timing
diff --git a/src/bitn/utils/init.lua b/src/bitn/utils/init.lua
index 9004ddb..b6b08e3 100644
--- a/src/bitn/utils/init.lua
+++ b/src/bitn/utils/init.lua
@@ -1,6 +1,8 @@
 --- @module "bitn.utils"
 --- Utility modules for bitn
+--- @class bitn.utils
 local utils = {
+  --- @type bitn.utils.benchmark Benchmarking utilities
   benchmark = require("bitn.utils.benchmark"),
 }