4 files changed, 52 insertions(+), 5 deletions(-)

A .luarc.json
M init.lua
M lib.lua
M shell.nix

@@ 0,0 1,3 @@
+{
+  "Lua.diagnostics.disable": ["lowercase-global"]
+}

@@ 1,16 1,21 @@
 local modname = "extruder"
 extruder = {}
 
+---@module 'lib'
 local lib = dofile(minetest.get_modpath(modname) .. "/lib.lua")
 
 minetest.register_privilege("extruder")
 
 -- TODO look into integrating with stuff like worldedit undo
 
+---@param meta minetest.MetaDataRef
+---@return integer
 local function meta_get_amount(meta)
   return math.max(1, meta:get_int("amount"))
 end
 
+---@param meta minetest.MetaDataRef
+---@param amount integer?
 local function meta_set_amount(meta, amount)
   if (not amount) or (amount < 1) then amount = 1 end
   meta:set_int("amount", amount)


@@ 18,7 23,15 @@ local function meta_set_amount(meta, amount)
 end
 
 
+---@alias surface_table {[string]: minetest.Node | false | nil}
+
+---@param visited surface_table
+---@param to_visit vector.Vector[]
+---@param direction vector.Vector
+---@param neighbors vector.Vector[]
+---@param node_name string?
 local function visit_wrapped(visited, to_visit, direction, neighbors, node_name)
+  ---@type vector.Vector
   local pos = table.remove(to_visit)
   while pos do
     if visited[vector.to_string(pos)] == nil then


@@ 41,6 54,10 @@ local function visit_wrapped(visited, to_visit, direction, neighbors, node_name)
   end
 end
 
+---@param pos vector.Vector
+---@param direction vector.Vector
+---@param meta minetest.MetaDataRef
+---@return surface_table
 local function visit(pos, direction, meta)
   local diagonal = lib.meta_get_bool(meta, "diagonal")
   local same_node = lib.meta_get_bool(meta, "same_node")


@@ 59,6 76,10 @@ local function visit(pos, direction, meta)
   return visited
 end
 
+---@param surface surface_table
+---@param direction vector.Vector
+---@param meta minetest.MetaDataRef
+---@param remove boolean
 local function extrude(surface, direction, meta, remove)
   local amount = meta_get_amount(meta)
   local overwrite = lib.meta_get_bool(meta, "overwrite")


@@ 68,6 89,8 @@ local function extrude(surface, direction, meta, remove)
   for pos_str,node in pairs(surface) do
     if node then
       local pos = vector.from_string(pos_str)
+      -- TODO explain the cast
+      ---@cast pos vector.Vector
       if not remove then pos = vector.add(pos, direction) end
       for _ = 1, amount do
         if remove then


@@ 84,6 107,10 @@ local function extrude(surface, direction, meta, remove)
   end
 end
 
+---@param placer minetest.Player?
+---@param pointed_thing any? # TODO
+---@param meta minetest.MetaDataRef
+---@param remove boolean
 local function use(placer, pointed_thing, meta, remove)
   if placer == nil or pointed_thing == nil or pointed_thing.type ~= "node" then return end
   if not lib.check_privs_with_msg(placer, "extruder") then return end

@@ 1,9 1,15 @@
 local lib = {}
 
+---@param player_or_name string | minetest.Player
+---@param privs string | minetest.Privs
+---@return boolean
 function lib.check_privs_with_msg(player_or_name, privs)
   local success, missing_privs = minetest.check_player_privs(player_or_name, privs)
   if not success then
-    local player_name = type(player_or_name) == "string" and player_or_name or player_or_name:get_player_name()
+    local player_name = type(player_or_name) == "string"
+                    and player_or_name
+		    ---@cast player_or_name minetest.Player
+		    or player_or_name:get_player_name()
     minetest.chat_send_player(player_name, "Missing privileges: " .. minetest.privs_to_string(missing_privs))
     return false
   end


@@ 11,15 17,23 @@ function lib.check_privs_with_msg(player_or_name, privs)
 end
 
 -- https://github.com/minetest/minetest/pull/12894
+---@param meta minetest.MetaDataRef
+---@param name string
+---@return boolean
 function lib.meta_get_bool(meta, name)
   return minetest.is_yes(meta:get(name) or "true")
 end
+---@param meta minetest.MetaDataRef
+---@param name string
+---@param value boolean
 function lib.meta_set_bool(meta, name, value)
   meta:set_string(name, value and "true" or "false")
 end
 
--- Get the four unit vectors parallel to axes
--- that are perpendicular to a given one (also parallel to an axis)
+---Get the four unit vectors parallel to axes
+---that are perpendicular to a given one (also parallel to an axis)
+---@param vec vector.Vector
+---@return vector.Vector[]
 function lib.get_perpendiculars(vec)
   if vec.x ~= 0 then
     return {


@@ 46,8 60,10 @@ function lib.get_perpendiculars(vec)
   }
 end
 
--- Get the four diagonal (wrt axes) "manhattan-unit" vectors
--- perpendicular to a given one (parallel to an axis)
+---Get the four diagonal (wrt axes) "manhattan-unit" vectors
+---perpendicular to a given one (parallel to an axis)
+---@param vec vector.Vector
+---@return vector.Vector[]
 function lib.get_diagonals(vec)
   if vec.x ~= 0 then
     return {

@@ 6,5 6,6 @@ pkgs.mkShell {
     pkgs.luajit
     pkgs.luaPackages.luacheck
     pkgs.jq
+    pkgs.lua-language-server
   ];
 }