More documentation

* Documented the item table
* Documented the inventory table
* Started writing tutorials

6 files changed, 24 insertions, 13 deletions

diff --git a/gamemode/core/inventory/cl_invtracker.lua b/gamemode/core/inventory/cl_invtracker.lua
index fdf5be3..e808627 100644
--- a/gamemode/core/inventory/cl_invtracker.lua
+++ b/gamemode/core/inventory/cl_invtracker.lua
@@ -1,6 +1,7 @@
---[[
-	One of the tabs in the inventory
-]]
+---Keeps track of inventories on the client side.
+--@client cl_invtracker.lua
+--@alias q
+
 local inv = nrequire("inventory/inventory.lua")
 local itm = nrequire("item.lua")
 nrequire("cl_loadglobals.lua")
@@ -11,6 +12,9 @@ local q = {}
 local known_inventories = {}
 local inventory_frames = {}
 local invsheet
+
+---An array of all the known inventories.
+--@export
 q.known_inventories = known_inventories
 
 local drawfloatinginventory = function(id, inventory)
diff --git a/gamemode/core/inventory/common/items.lua b/gamemode/core/inventory/common/items.lua
index 4b52a97..0a32f27 100644
--- a/gamemode/core/inventory/common/items.lua
+++ b/gamemode/core/inventory/common/items.lua
@@ -1,6 +1,7 @@
 ---Some common functions for working with items.
 -- Just one function for now
 --@shared items.lua
+--@alias items
 
 local items = {}
 
diff --git a/gamemode/core/inventory/common/weapons.lua b/gamemode/core/inventory/common/weapons.lua
index 065d1a6..9067981 100644
--- a/gamemode/core/inventory/common/weapons.lua
+++ b/gamemode/core/inventory/common/weapons.lua
@@ -1,6 +1,7 @@
 ---Common functionality used in a lot of weapons.
 -- Bits an peices that most weapons need
 --@shared weapons.lua
+--@alias com
 
 local com = {}
 
@@ -62,7 +63,7 @@ function com.swingarc(player,times,positions,onhit)
 	end)
 end
 
----Creates a new attack table
+---Creates a new attack table.
 -- Creates a table of ["forward|backward|left|right"] = function()
 -- This is done before hand so that table is not re-generated on the fly each time a player attacks
 --@tparam attacktbl tbl_attackdata The attack data to use
diff --git a/gamemode/core/inventory/inventory.lua b/gamemode/core/inventory/inventory.lua
index 1290519..ea1d33e 100644
--- a/gamemode/core/inventory/inventory.lua
+++ b/gamemode/core/inventory/inventory.lua
@@ -1,6 +1,7 @@
 ---The main file needed to register create new inventory types.
 -- Helps you register inventories that work with the rest of artery
 --@shared inventory.lua
+--@alias inv
 
 --[[
 	Public functions:
diff --git a/gamemode/core/inventory/item.lua b/gamemode/core/inventory/item.lua
index 9a6a293..79f9ad5 100644
--- a/gamemode/core/inventory/item.lua
+++ b/gamemode/core/inventory/item.lua
@@ -1,6 +1,8 @@
 ---The main module to use when createing new items.
 -- Registers items that will work with the inventory system
 --@shared item.lua
+--@alias itm
+
 --[[
 	An itemsystem
 	public functions:
@@ -18,7 +20,6 @@
 		item:DeSerialize(string_data)	::nil
 			Recreate an item. If this item has any instance specific data, it should return a table.Copy(self) with the appropriate fields set.
 		The above must be defined for every item
-	Items may also have methods from one or more interfaces registered with RegisterInterface
 ]]
 
 local log = nrequire("log.lua")
@@ -31,8 +32,7 @@ local items = items or {} --Master table of all item prototypes
 
 ---Registers an item.
 -- Registers an item that can be gotten later. It usually dosn't make sense for only parts of the level to have an item (the player probably can travel between all the parts of your world with the item in their inventory), therefore you should make sure items are loaded globally.
---@see itemtbl
---@tparam table tbl The table to register for the item prototype
+--@tparam itemtbl tbl The table to register for the item prototype
 function itm.RegisterItem(tbl)
 	for k,v in pairs(required_fields) do
 		assert(tbl[v] ~= nil, string.format("Attempted to register item without field %q",v))
@@ -50,7 +50,7 @@ end
 ---Gets an instance of an item.
 -- Gets an instanced copy of an item registered with RegisterItem()
 --@tparam string name The name of the item
---@treturn itemtbl item The item
+--@treturn itemtbl The item
 function itm.GetItemByName(name)
 	assert(type(name) == "string",string.format("Attempted to get an item by name with a %s.",type(name)))
 	assert(items[name] ~= nil,string.format("Attempted to get item with invalid name %q Valid item names are:\n\t%s",name,table.concat(table.GetKeys(items),"\n\t")))
@@ -67,6 +67,7 @@ end
 -- Just gets the item, then calls DeSerialize(), returning whatever deserialize returned
 --@tparam string name The name of the item
 --@tparam string data The data to instantiate the item with
+--@treturn itemtbl The item that was deserialized
 function itm.GetItemFromData(name,data)
 	assert(items[name] ~= nil,string.format("Attempted to get item with invalid name %q",name))
 	return items[name]:DeSerialize(data)
@@ -101,6 +102,9 @@ end
 
 hook.Call("artery_include_items")
 
-concommand.Add("art_printitems",printitems)
+---Prints a list of all items the client/server knows about
+--@concommand artery_printitems
+--@usage artery_printitems
+concommand.Add("artery_printitems",printitems)
 
 return itm
diff --git a/gamemode/core/inventory/sv_invtracker.lua b/gamemode/core/inventory/sv_invtracker.lua
index e009828..88de42e 100644
--- a/gamemode/core/inventory/sv_invtracker.lua
+++ b/gamemode/core/inventory/sv_invtracker.lua
@@ -1,8 +1,7 @@
 ---Utilities to help deal with inventories.
 -- Helps you display, manage, and manipulate inventories
 --@server sv_invtracker.lua
-
---@domain Server
+--@alias track
 
 --[[
 	some accessability functions
@@ -65,7 +64,7 @@ end)
 
 ---Drops an item at the position.
 -- Creates a droped item at the given position, gives the player that walks over it the item.
---@tparam itmtbl item The item to drop
+--@tparam itemtbl item The item to drop
 --@tparam vector3 pos The position to drop the item
 function track.DropItem(item,pos)
 	local e = ents.Create("art_droppeditem")
@@ -287,7 +286,6 @@ end
 
 ---Prints a player's inventory to the console.
 --@concommand artery_ShowMyInventories
---@reqadmin
 concommand.Add("artery_ShowMyInventories",
 
 function(ply,cmd,args)
@@ -298,6 +296,7 @@ end)
 -- Gives a new inventory to a player ![Requires admin](./req_admin)
 --@usage artery_AddInventory <inventory name>
 --@concommand artery_AddInventory
+--@reqadmin
 concommand.Add("artery_AddInventory",function(ply,cmd,args)
 	if not ply:IsAdmin() then return end
 	track.GiveInventoryTo(ply,args[1])
@@ -307,6 +306,7 @@ end)
 -- Gives a new item to the player ![Requires admin](./req_admin)
 --@usage artery_GiveItem <item name>
 --@concommand artery_GiveItem
+--@reqadmin
 concommand.Add("artery_GiveItem",function(ply,cmd,args)
 	if not ply:IsAdmin() then return end
 	xpcall(function()