add ldoc documentation

.cdb.json

@@ -15,5 +15,6 @@
     "repo": "https://bitbucket.org/minetest_gamers/x_bows/src/master/",
     "issue_tracker": "https://bitbucket.org/minetest_gamers/x_bows/issues?status=new&status=open",
     "forums": 26466,
-    "video_url": "https://youtu.be/pItpltmUoa8"
+    "video_url": "https://youtu.be/pItpltmUoa8",
+    "website": "https://bitbucket.org/minetest_gamers/x_bows/wiki/Home"
 }

.gitignore

@@ -1 +1,2 @@
 .DS_Store
+docs/build

api.lua

@@ -1882,7 +1882,7 @@ function XBowsQuiver.quiver_can_allow(self, inv, player)
 end
 
 ---Open quiver
----@param self XBowsQuiver
+---@param self XBows
 ---@param itemstack ItemStack
 ---@param user ObjectRef
 ---@return ItemStack

config.ld

@@ -0,0 +1,8 @@
+file = {"docs"}
+title = "x_bows API documentation"
+description = "Minetest mod"
+format = "markdown"
+dir = "docs/build"
+readme = "README.md"
+project = "x_bows"
+ext = "html"

docs/x_bows_api.lua

@@ -0,0 +1,126 @@
+----
+-- Base XBows class
+-- @author SaKeL
+-- @license LGPL-2.1-or-later
+-- @classmod XBows
+XBows = {
+    --- `enable_pvp` setting, default `false`
+    pvp = false,
+    --- `creative_mode` setting, default `false`
+    creative = false,
+    --- `mesecons` check if MOD enabled or exists
+    mesecons = false,
+    --- `playerphysics` check if MOD enabled or exists
+    playerphysics = false,
+    --- `player_monoids` check if MOD enabled or exists
+    player_monoids = false,
+    --- table with key/value pairs, `key` is the item name (e.g. `x_bows:bow_wood`), `value` is the definition passed to XBows register method
+    registered_bows = {},
+    --- table with key/value pairs, `key` is the item name (e.g. `x_bows:arrow_wood`), `value` is the definition passed to XBows register method
+    registered_arrows = {},
+    --- table with key/value pairs, `key` is the item name (e.g. `x_bows:quiver`), `value` is the definition passed to XBows register method
+    registered_quivers = {},
+    --- registered particle spawners for internal use
+    registered_particle_spawners = {},
+    --- sneaking players when bow is charged
+    player_bow_sneak = {},
+    --- `Settings` from minetest
+    settings = {
+        --- `x_bows_attach_arrows_to_entities` setting, default: `false`
+        x_bows_attach_arrows_to_entities = false
+    },
+    --- table of `after` jobs
+    charge_sound_after_job = {}
+}
+
+---Check if creative is enabled or if player has creative priv
+-- @param self XBows
+-- @param name string
+-- @return boolean
+function XBows.is_creative(self, name) end
+
+---Updates `allowed_ammunition` definition on already registered item, so MODs can add new ammunitions to this list.
+-- @param self XBows
+-- @param name string
+-- @param allowed_ammunition string[]
+-- @return nil
+function XBows.update_bow_allowed_ammunition(self, name, allowed_ammunition) end
+
+---Reset charged bow to uncharged bow, this will return the arrow item to the inventory also
+-- @param self XBows
+-- @param player ObjectRef Player Ref
+-- @param includeWielded? boolean Will include reset for wielded bow also. default: `false`
+-- @return nil
+function XBows.reset_charged_bow(self, player, includeWielded) end
+
+---Register bows
+-- @param self XBows
+-- @param name string
+-- @param def ItemDef | BowItemDefCustom
+-- @param override? boolean MOD everride
+-- @return boolean|nil
+function XBows.register_bow(self, name, def, override) end
+
+---Register arrows
+-- @param self XBows
+-- @param name string
+-- @param def ItemDef | ArrowItemDefCustom
+-- @return boolean|nil
+function XBows.register_arrow(self, name, def) end
+
+---Register quivers
+-- @param self XBows
+-- @param name string
+-- @param def ItemDef | QuiverItemDefCustom
+-- @return boolean|nil
+function XBows.register_quiver(self, name, def) end
+
+---Load bow
+-- @param self XBows
+-- @param itemstack ItemStack
+-- @param user ObjectRef
+-- @param pointed_thing PointedThingDef
+-- @return ItemStack
+function XBows.load(self, itemstack, user, pointed_thing) end
+
+---Shoot bow
+-- @param self XBows
+-- @param itemstack ItemStack
+-- @param user ObjectRef
+-- @param pointed_thing? PointedThingDef
+-- @return ItemStack
+function XBows.shoot(self, itemstack, user, pointed_thing) end
+
+---Add new particle to XBow registration
+-- @param self XBows
+-- @param name string
+-- @param def ParticlespawnerDef|ParticlespawnerDefCustom
+-- @return nil
+function XBows.register_particle_effect(self, name, def) end
+
+---Get particle effect from registered spawners table
+-- @param self XBows
+-- @param name string
+-- @param pos Vector
+-- @return number|boolean
+function XBows.get_particle_effect_for_arrow(self, name, pos) end
+
+---Check if ammunition is allowed to charge this weapon
+-- @param self XBows
+-- @param weapon_name string
+-- @param ammo_name string
+-- @return boolean
+function XBows.is_allowed_ammunition(self, weapon_name, ammo_name) end
+
+---Register new projectile entity
+-- @param self XBows
+-- @param name string
+-- @param def XBowsEntityDef
+function XBows.register_entity(self, name, def) end
+
+---Open quiver
+-- @param self XBows
+-- @param itemstack ItemStack
+-- @param user ObjectRef
+-- @return ItemStack
+function XBows.open_quiver(self, itemstack, user) end

docs/x_bows_quiver_api.lua

@@ -0,0 +1,88 @@
+----
+-- XBowsQuiver class extended from XBows
+-- @author SaKeL
+-- @license LGPL-2.1-or-later
+-- @classmod XBowsQuiver
+XBowsQuiver = {
+    --- IDs of added HUDs
+    hud_item_ids = {},
+    --- `after` job tables
+    after_job = {}
+}
+
+---Close one or all open quivers in players inventory
+-- @param self XBowsQuiver
+-- @param player ObjectRef
+-- @param quiver_id? string If `nil` then all open quivers will be closed
+-- @return nil
+function XBowsQuiver.close_quiver(self, player, quiver_id) end
+
+---Swap item in player inventory indicating open quiver. Preserve all ItemStack definition and meta.
+-- @param self XBowsQuiver
+-- @param from_stack ItemStack transfer data from this item
+-- @param to_item_name string transfer data to this item
+-- @return ItemStack ItemStack replacement item
+function XBowsQuiver.get_replacement_item(self, from_stack, to_item_name) end
+
+---Gets arrow from quiver
+-- @param self XBowsQuiver
+-- @param player ObjectRef
+-- @return {["found_arrow_stack"]: ItemStack|nil, ["quiver_id"]: string|nil, ["quiver_name"]: string|nil, ["found_arrow_stack_idx"]: number}
+function XBowsQuiver.get_itemstack_arrow_from_quiver(self, player) end
+
+---Remove all added HUDs
+-- @param self XBowsQuiver
+-- @param player ObjectRef
+-- @return nil
+function XBowsQuiver.remove_hud(self, player) end
+
+---Update or create quiver HUD
+-- @param self XBowsQuiver
+-- @param player ObjectRef
+-- @param inv_list ItemStack[]
+-- @param idx? number
+-- @return nil
+-- @todo implement hud_change?
+function XBowsQuiver.udate_or_create_hud(self, player, inv_list, idx) end
+
+---Get existing detached inventory or create new one
+-- @param self XBowsQuiver
+-- @param quiver_id string
+-- @param player_name string
+-- @param quiver_items? string
+-- @return InvRef|unknown
+function XBowsQuiver.get_or_create_detached_inv(self, quiver_id, player_name, quiver_items) end
+
+---Create formspec
+-- @param self XBowsQuiver
+-- @param name string name of the form
+-- @return string
+function XBowsQuiver.get_formspec(self, name) end
+
+---Convert inventory of itemstacks to serialized string
+-- @param self XBowsQuiver
+-- @param inv InvRef
+-- @return {['inv_string']: string, ['content_description']: string}
+function XBowsQuiver.get_string_from_inv(self, inv) end
+
+---Set items from serialized string to inventory
+-- @param self XBowsQuiver
+-- @param inv InvRef inventory to add items to
+-- @param str string previously stringified inventory of itemstacks
+-- @return nil
+function XBowsQuiver.set_string_to_inv(self, inv, str) end
+
+---Save quiver inventory to itemstack meta
+-- @param self XBowsQuiver
+-- @param inv InvRef
+-- @param player ObjectRef
+-- @param quiver_is_closed? boolean
+-- @return nil
+function XBowsQuiver.save(self, inv, player, quiver_is_closed) end
+
+---Check if we are allowing actions in the correct quiver inventory
+-- @param self XBowsQuiver
+-- @param inv InvRef
+-- @param player ObjectRef
+-- @return boolean
+function XBowsQuiver.quiver_can_allow(self, inv, player) end