docs: class namespaces follow directories

lua/libmodal/init.lua

@@ -1,5 +1,5 @@
--- TODO: remove the __index here after a period of time to let people remove `libmodal.Layer` from their configurations
+--- @class libmodal
-return setmetatable(
+local libmodal = setmetatable(
 	{
 		layer =
 		{
@@ -67,3 +67,5 @@ return setmetatable(
 		end,
 	}
 )
+
+return libmodal

lua/libmodal/src/Layer.lua

@@ -1,8 +1,5 @@
---- @type libmodal.globals
 local globals = require 'libmodal.src.globals'
-
+local utils = require 'libmodal.src.utils' --- @type libmodal.utils
---- @type libmodal.utils
-local utils = require 'libmodal.src.utils'
 
 --- Normalizes a `buffer = true|false|0` argument into a number.
 --- @param buffer boolean|number the argument to normalize

lua/libmodal/src/Mode.lua

@@ -1,5 +1,5 @@
-local globals = require 'libmodal.src.globals' --- @type libmodal.globals
+local globals = require 'libmodal.src.globals'
-local ParseTable = require 'libmodal.src.collections.ParseTable' --- @type libmodal.collections.ParseTable
+local ParseTable = require 'libmodal.src.collections.ParseTable'
 local utils = require 'libmodal.src.utils' --- @type libmodal.utils
 
 --- @class libmodal.Mode
@@ -214,18 +214,16 @@ function Mode.new(name, instruction, supress_exit)
 
 		-- determine if a default `Help` should be created.
 		if not self.instruction[HELP_CHAR] then
-			--- @diagnostic disable-next-line:param-type-mismatch we checked that `instruction` is a table above
+			self.help = utils.Help.new(instruction, 'KEY MAP')
-			self.help = utils.Help.new(self.instruction, 'KEY MAP')
 		end
 
 		self.input_bytes = {}
 
 		-- build the parse tree.
-		--- @diagnostic disable-next-line:param-type-mismatch already checked `self.instruction` != `table`
+		self.mappings = ParseTable.new(instruction)
-		self.mappings = ParseTable.new(self.instruction)
 
 		-- create a table for mode-specific data.
-		self.popups = require('libmodal.src.collections.Stack').new()
+		self.src.popups = require('libmodal.collections.Stack').new()
 
 		-- create a variable for whether or not timeouts are enabled.
 		self.timeouts = utils.Vars.new('timeouts', self.name)

lua/libmodal/src/collections/ParseTable.lua

@@ -4,7 +4,7 @@ local utils = require('libmodal.src.utils') --- @type libmodal.utils
 local CR = utils.api.replace_termcodes('<CR>'):byte()
 
 --- @class libmodal.collections.ParseTable
---- @field CR number the byte representation of `<CR>`
+--- @field CR integer the byte representation of `<CR>`
 local ParseTable = utils.classes.new {CR = CR}
 
 --- reverse the order of elements in some `list`.

lua/libmodal/src/collections/Stack.lua

@@ -1,7 +1,9 @@
---- @class libmodal.collections.Stack
+--- @class libmodal.collections.Stack<T>
+--- @field private [number] T
 local Stack = require('libmodal.src.utils.classes').new()
 
---- @return libmodal.collections.Stack
+--- @generic T
+--- @return libmodal.collections.Stack<T>
 function Stack.new()
 	return setmetatable({}, Stack)
 end

lua/libmodal/src/init.lua

@@ -1,18 +0,0 @@
---- @class libmodal
---- @field collections libmodal.collections
---- @field globals libmodal.globals
---- @field Layer libmodal.Layer
---- @field Mode libmodal.Mode
---- @field Prompt libmodal.Prompt
---- @field utils libmodal.utils
-local libmodal =
-{
-	collections = require 'libmodal.src.collections',
-	globals = require 'libmodal.src.globals',
-	Layer = require 'libmodal.src.Layer',
-	Mode = require 'libmodal.src.Mode',
-	Prompt = require 'libmodal.src.Prompt',
-	utils = require 'libmodal.src.utils',
-}
-
-return libmodal

lua/libmodal/src/utils/Help.lua

@@ -1,4 +1,5 @@
 --- @class libmodal.utils.Help
+--- @field private [integer] string[]
 local Help = require('libmodal.src.utils.classes').new()
 
 --- align `tbl` according to the `longest_key_len`.

lua/libmodal/src/utils/Popup.lua

@@ -1,7 +1,7 @@
 --- @class libmodal.utils.Popup
---- @field private buffer number the number of the window which this popup is rendered on.
+--- @field private buffer_number integer the number of the window which this popup is rendered on.
 --- @field private input_chars string[] the characters input by the user.
---- @field private window number the number of the window which this popup is rendered on.
+--- @field private window_number integer the number of the window which this popup is rendered on.
 local Popup = require('libmodal.src.utils.classes').new()
 
 --- @param window number
@@ -15,22 +15,22 @@ end
 --- @param keep_buffer boolean `self.buffer` is passed to `nvim_buf_delete` unless `keep_buffer` is `false`
 --- @return nil
 function Popup:close(keep_buffer)
-	if valid(self.window) then
+	if valid(self.window_number) then
-		vim.api.nvim_win_close(self.window, false)
+		vim.api.nvim_win_close(self.window_number, false)
 	end
 
-	self.window = nil
+	self.window_number = nil
 
 	if not keep_buffer then
-		vim.api.nvim_buf_delete(self.buffer, {force = true})
+		vim.api.nvim_buf_delete(self.buffer_number, {force = true})
-		self.buffer = nil
+		self.buffer_number = nil
 		self.input_chars = nil
 	end
 end
 
 --- @return libmodal.utils.Popup
 function Popup.new(config)
-	local self = setmetatable({buffer = vim.api.nvim_create_buf(false, true), input_chars = {}}, Popup)
+	local self = setmetatable({buffer_number = vim.api.nvim_create_buf(false, true), input_chars = {}}, Popup)
 	self:open(config)
 	return self
 end
@@ -52,14 +52,14 @@ function Popup:open(config)
 		}
 	end
 
-	if valid(self.window) then
+	if valid(self.window_number) then
 		self:close(true)
 	end
 
-	self.window = vim.api.nvim_open_win(self.buffer, false, config)
+	self.window_number = vim.api.nvim_open_win(self.buffer_number, false, config)
 
 	-- HACK: the window always pops up with the wrong width, but this makes it work :shrug:
-	vim.api.nvim_win_set_width(self.window, config.width)
+	vim.api.nvim_win_set_width(self.window_number, config.width)
 end
 
 --- display `input_bytes` in `self.buffer`
@@ -78,14 +78,14 @@ function Popup:refresh(input_bytes)
 		end
 	end
 
-	vim.api.nvim_buf_set_lines(self.buffer, 0, 1, true, {table.concat(self.input_chars)})
+	vim.api.nvim_buf_set_lines(self.buffer_number, 0, 1, true, {table.concat(self.input_chars)})
 
 	-- close and reopen the window if it was not already open.
-	if not valid(self.window) or vim.api.nvim_win_get_tabpage(self.window) ~= vim.api.nvim_get_current_tabpage() then
+	if not valid(self.window_number) or vim.api.nvim_win_get_tabpage(self.window_number) ~= vim.api.nvim_get_current_tabpage() then
 		self:open()
 	end
 
-	vim.api.nvim_win_set_width(self.window, #self.input_chars)
+	vim.api.nvim_win_set_width(self.window_number, #self.input_chars)
 end
 
 return Popup

lua/libmodal/src/utils/api.lua

@@ -1,4 +1,4 @@
-local globals = require 'libmodal.src.globals' --- @type libmodal.globals
+local globals = require 'libmodal.src.globals'
 
 --- @class libmodal.utils.api
 local api = {}