Finished LDoc comments

5 files changed, 115 insertions, 14 deletions

diff --git a/gamemode/core/inventory/common/items.lua b/gamemode/core/inventory/common/items.lua
index 868d940..a7a1858 100644
--- a/gamemode/core/inventory/common/items.lua
+++ b/gamemode/core/inventory/common/items.lua
@@ -1,3 +1,6 @@
+---Some common functions for working with items.
+-- Just one function for now
+--@module items.lua
 
 local items = {}
 
@@ -10,7 +13,11 @@ local items = {}
 -- 	net.SendToServer()
 -- end
 
---Client requests the item be droped from the ent, invid, and inv position
+---Drops an item.
+-- Client side only, will error if you try to use it server side
+--@tparam entity ent_or_tbl the entity that wants to drop the item
+--@tparam number invid The inventory number the entity wants to drop from
+--@tparam table frompos The position in the inventory the item was in.
 function items.DropItem(ent_or_tbl,invid,frompos)
 	--[[
 	if type(ent_or_tbl) == "table" then
diff --git a/gamemode/core/inventory/common/weapons.lua b/gamemode/core/inventory/common/weapons.lua
index 0a86f00..3ced3b1 100644
--- a/gamemode/core/inventory/common/weapons.lua
+++ b/gamemode/core/inventory/common/weapons.lua
@@ -1,6 +1,6 @@
---[[
-	Some common functionality that many weapons need
-]]
+---Common functionality used in a lot of weapons.
+-- Bits an peices that most weapons need
+--@module weapons.lua
 
 local com = {}
 
@@ -25,7 +25,7 @@ end
 --- The arc swing of a weapon.
 -- Finds anything that a weapon should hit in it's swing, and calls a function on it.
 -- @param player The player that's swinging the weapon
--- @param tiems A table of times that the trace calculations should be done at, this table needs to be the same length as the positions table
+-- @param times A table of times that the trace calculations should be done at, this table needs to be the same length as the positions table
 -- @param positions The position offsets from the player that swung that should be the start/end points of the arc
 -- @param onhit A function to call on any entities that were hit in the swing of the weapon.
 function com.swingarc(player,times,positions,onhit)
@@ -62,8 +62,11 @@ function com.swingarc(player,times,positions,onhit)
 	end)
 end
 
---Creates a table of ["forward|backward|left|right"] = function()
---When called, the function does an attack.
+---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
+--@tparam entity attacker The entity attacking
 function com.createattackstable(tbl_attackdata,attacker)
 	local movementtbl = {}
 	for k,v in pairs(tbl_attackdata) do
diff --git a/gamemode/core/inventory/inventory.lua b/gamemode/core/inventory/inventory.lua
index 4624819..69e8181 100644
--- a/gamemode/core/inventory/inventory.lua
+++ b/gamemode/core/inventory/inventory.lua
@@ -1,3 +1,7 @@
+---The main file needed to register create new inventory types.
+-- Helps you register inventories that work with the rest of artery
+--@module inventory.lua
+
 --[[
 	Public functions:
 		RegisterInventory(tbl_inventory)	::nil
@@ -111,6 +115,10 @@ local required_fields = {
 	{"Serialize","function"},
 	{"DeSerialize","function"},
 }
+---Registers a new inventory.
+-- Register a new inventory prototype from the table passed in
+--@see invtbl
+--@tparam invtbl tbl The table inventory
 function inv.RegisterInventory(tbl)
 	assert(type(tbl) == "table",
 	       "Attempted to register inventory that was not a table")
@@ -136,7 +144,11 @@ function inv.RegisterInventory(tbl)
 	--print("Registered inventory: " .. tbl.Name)
 end
 
---Create an inventory
+---Create an inventory.
+-- Creates a new inventory that you can give to an item.
+-- Consider carefully if you want to use this method, or the CreateInventoryFromData method.
+--@see invtbl
+--@tparam string name The name of the inventory type when it was registered
 function inv.CreateInventory(name)
 	--print("Createing inventory", name)
 	assert(inventories[name] ~= nil, string.format("Tried to create a copy of inventory that does not exist:%s\nValid inventories are:\n\t%s",name,table.concat(table.GetKeys(inventories),"\n\t")))
@@ -145,7 +157,11 @@ function inv.CreateInventory(name)
 	return ret
 end
 
---Recreates an inventory from data
+---Creates an inventory from data.
+-- This is what you useually want to use when createing inventories
+--@tparam string name The name of the inventory type you want to instanciate
+--@tparam string data The data the inventory needs to deserialize, most inventories will work if this is empty
+--@tparam entity owner The owning entity of this inventory, does not have to be a player (ex when createing crates players can put items into)
 function inv.CreateInventoryFromData(name,data,owner)
 	local tinv = inv.CreateInventory(name)
 	tinv.Owner = owner
@@ -158,7 +174,7 @@ function inv.CreateInventoryFromData(name,data,owner)
 	return ret
 end
 
---Must be called in a coroutine.
+---To Be Depriciated.
 function inv.DeriveInventory(name)
 	while inventories[name] == nil do
 		coroutine.yield()
diff --git a/gamemode/core/inventory/item.lua b/gamemode/core/inventory/item.lua
index 2eb2fb3..1e6a0cf 100644
--- a/gamemode/core/inventory/item.lua
+++ b/gamemode/core/inventory/item.lua
@@ -1,3 +1,6 @@
+---The main module to use when createing new items.
+-- Registers items that will work with the inventory system
+--@module item.lua
 --[[
 	An itemsystem
 	public functions:
@@ -25,6 +28,11 @@ local required_fields = {
 }
 
 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
 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))
@@ -39,6 +47,10 @@ function itm.RegisterItem(tbl)
 	--print("Registered item: " .. tbl.Name)
 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
 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")))
@@ -51,6 +63,10 @@ function itm.GetItemByName(name)
 	return item
 end
 
+---Gets an item, with data.
+-- 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
 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)
@@ -64,7 +80,7 @@ local function printitems()
 	print(table.concat(tbl,"\n"))
 end
 
---Must be called in a coroutine.
+---To be depriciated.
 function itm.DeriveItem(tbl,name)
 	print("Attempting to derive item",name)
 	while items[name] == nil do
diff --git a/gamemode/core/inventory/sv_invtracker.lua b/gamemode/core/inventory/sv_invtracker.lua
index 310af0f..67e32a1 100644
--- a/gamemode/core/inventory/sv_invtracker.lua
+++ b/gamemode/core/inventory/sv_invtracker.lua
@@ -1,3 +1,7 @@
+---Utilities to help deal with inventories.
+-- Helps you display, manage, and manipulate inventories
+--@module sv_invtracker.lua
+
 --[[
 	some accessability functions
 ]]
@@ -57,6 +61,10 @@ net.Receive("art_RequestInvMove",function(len,ply)
 	toinv:Put(topos,item)
 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 vector3 pos The position to drop the item
 function track.DropItem(item,pos)
 	local e = ents.Create("art_droppeditem")
 	e.Item = {Name = item.Name, Data = item:Serialize()}
@@ -100,11 +108,16 @@ net.Receive("art_RequestInvDrop",function(len,ply)
 	track.DropItem(item,placetodrop)
 end)
 
+---To be depriciated.
+-- Also broken
 function track.ClearInventories(ply)
 	ply.data = {}
 end
 
---Updates the client side inventory whenever the inventory is updated server side
+---Updates clients.
+-- Updates the clients, to let them know an inventory was manipulated whenever the server-side representation was manipulated
+--@tparam player ply The player we want to provide the updates to
+--@tparam number invid The inventory number on the player we want to provide the updates to
 function track.MakeInventoryObserver(ply,invid)
 	print("Making observer...")
 	local observer = {}
@@ -133,6 +146,10 @@ function track.MakeInventoryObserver(ply,invid)
 	return observer
 end
 
+---Tell a player to display an inventory.
+-- Tells a player they should display an inventory, and to expect changes to the inventory.
+--@tparam player ply The player we want to see the inventory
+--@tparam invtbl tinv The inventory we want the player to see
 function track.NotifyPlayerOfInventory(ply,tinv)
 	local initaldat = tinv:Serialize()
 	net.Start("art_ObserveInventory")
@@ -146,6 +163,12 @@ function track.NotifyPlayerOfInventory(ply,tinv)
 	net.Send(ply)
 end
 
+---Gives an inventory to a player.
+-- Gives a new inventory type to a player
+--@see inventory_higharchy
+--@tparam entity ply The player to give an inventory to
+--@tparam string name The name of the inventory to give
+--@tparam table|nil higharchy The higharchy where to put the table
 function track.GiveInventoryTo(ply,name,higharchy)
 	local hi = higharchy or {}
 	local i = inv.CreateInventory(name)
@@ -167,6 +190,13 @@ function track.GiveInventoryTo(ply,name,higharchy)
 	net.Send(ply)
 end
 
+---Gives an inventory to a palyer & deserializes data.
+-- Gives an inventory to a player, and then deserializes it with some data.
+--@see inventory_higharchy
+--@tparam entity ply The player to give the inventory to
+--@tparam string name The name of the inventory to give
+--@tparam string data The data to deserialize the inventory with
+--@tparam table|nil higharchy The spot in the higharchy to place the inventory.
 function track.GiveInventoryWithData(ply,name,data,higharchy)
 	local hi = higharchy or {}
 	print("Giveing inventory with data")
@@ -197,9 +227,12 @@ end
 
 
 
---A shortcut for finding if a player has an item
 local plymeta = FindMetaTable("Player")
-
+---A shortcut to check if a player has an item.
+-- Checks if a player has an item
+--@metamethod player:HasItem(str)
+--@tparam string str The name of the item to look for
+--@treturn table|false Returns the position if the player has the item, false if they don't
 function plymeta:HasItem(str)
 	for k,v in pairs(self.data.inventories) do
 		local p = v:Has(str)
@@ -210,6 +243,11 @@ function plymeta:HasItem(str)
 	return false
 end
 
+---A shortcut to remove an item from a player.
+-- Removes an item from a player and returns the item
+--@metamethod plymeta:RemoveItem(tbl)
+--@tparam table tbl The position the item is in (returned by plymeta:HasItem())
+--@treturn itemtbl The item that was removed
 function plymeta:RemoveItem(tbl)
 	print("Got remove table, it was",tbl)
 	PrintTable(tbl)
@@ -222,6 +260,11 @@ function plymeta:RemoveItem(tbl)
 	return item
 end
 
+---A shortcut for giving an item to a player.
+-- Gives an item to a player
+--@metamethod plymeta:GiveItem(tbl)
+--@param itemtbl tbl The item to give the player
+--@raises "Uanble to find place to put item" Raises an exception if we cannot find a location to put the item.
 function plymeta:GiveItem(tbl)
 	for k,v in pairs(self.data.inventories) do
 		local p = v:FindPlaceFor(tbl)
@@ -236,10 +279,14 @@ function plymeta:GiveItem(tbl)
 	error("Unable to find place to put item")
 end
 
+---Gets a player's credits.
+-- To be depriciated
 function plymeta:GetCredits()
 	return self.data.credits
 end
 
+---Sets a player's credits.
+-- To be depriciated
 function plymeta:SetCredits(num)
 	print("Set credits called")
 	self.data.credits = num
@@ -250,6 +297,8 @@ function plymeta:SetCredits(num)
 	net.Send(self)
 end
 
+---Sends a player's data.
+-- To be depriciated
 function track.SendPlayerData(ply)
 	net.Start("art_load_player_data")
 	net.WriteTable({
@@ -264,15 +313,25 @@ end
 -- 	track.SendPlayerData(ply)
 -- end)
 
+---Prints a player's inventory to the console.
+--@concommand artery_ShowMyInventories
 concommand.Add("artery_ShowMyInventories",function(ply,cmd,args)
 	PrintTable(ply.data.inventories)
 end)
 
+---Gives an inventory to a player.
+-- Gives a new inventory to a player ![Requires admin](./req_admin)
+--@usage artery_AddInventory <inventory name>
+--@concommand artery_AddInventory
 concommand.Add("artery_AddInventory",function(ply,cmd,args)
 	if not ply:IsAdmin() then return end
 	track.GiveInventoryTo(ply,args[1])
 end)
 
+---Gives an item to the player.
+-- Gives a new item to the player ![Requires admin](./req_admin)
+--@usage artery_GiveItem <item name>
+--@concommand artery_GiveItem
 concommand.Add("artery_GiveItem",function(ply,cmd,args)
 	if not ply:IsAdmin() then return end
 	xpcall(function()