From 910491740aabf752c3af7919e37e7a9b53c3b043 Mon Sep 17 00:00:00 2001 From: Juraj Vajda Date: Sat, 22 Oct 2022 23:20:02 -0400 Subject: [PATCH] add ldoc documentation --- .cdb.json | 3 +- .gitignore | 3 +- api.lua | 2 +- config.ld | 8 +++ docs/x_bows_api.lua | 126 +++++++++++++++++++++++++++++++++++++ docs/x_bows_quiver_api.lua | 88 ++++++++++++++++++++++++++ 6 files changed, 227 insertions(+), 3 deletions(-) create mode 100644 config.ld create mode 100644 docs/x_bows_api.lua create mode 100644 docs/x_bows_quiver_api.lua diff --git a/.cdb.json b/.cdb.json index dad2a35..1c34ee0 100644 --- a/.cdb.json +++ b/.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" } diff --git a/.gitignore b/.gitignore index 496ee2c..4f8931c 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ -.DS_Store \ No newline at end of file +.DS_Store +docs/build diff --git a/api.lua b/api.lua index 9be35bc..fe0586b 100644 --- a/api.lua +++ b/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 diff --git a/config.ld b/config.ld new file mode 100644 index 0000000..9477936 --- /dev/null +++ b/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" diff --git a/docs/x_bows_api.lua b/docs/x_bows_api.lua new file mode 100644 index 0000000..f0a656a --- /dev/null +++ b/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 diff --git a/docs/x_bows_quiver_api.lua b/docs/x_bows_quiver_api.lua new file mode 100644 index 0000000..1b3262e --- /dev/null +++ b/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