Merge pull request #403 from LengthenedGradient/Networking-and-Tool-D…

…ocumentation

Add Networking and Tool Documentation

lua/acf/core/classes/entities/registration.lua

@@ -1,3 +1,7 @@
+--[[
+The purpose of this class is to define a class that represents an entity, storing its spawn function as well as registering the arguments attached to the entity with duplicators.
+--]]
+
 local duplicator = duplicator
 local isfunction = isfunction
 local isstring   = isstring
@@ -7,7 +11,10 @@ local Classes    = ACF.Classes
 local Entities   = Classes.Entities
 local Entries    = {}
 
-
+--- Gets the entity table of a certain class
+--- If an entity table doesn't exist for the class, it will register one.
+--- @param Class table The class to get the entity table from
+--- @return {Lookup:table, Count:number, List:table} # The entity table of this class
 local function GetEntityTable(Class)
 	local Data = Entries[Class]
 
@@ -24,6 +31,11 @@ local function GetEntityTable(Class)
 	return Data
 end
 
+--- Adds arguments to an entity for storage in duplicators
+--- The Entity.Lookup, Entity.Count and Entity.List variables allow us to iterate over this information in different ways. 
+--- @param Entity entity The entity to add arguments to
+--- @param Arguments any[] # An array of arguments to attach to the entity (usually {...})
+--- @return any[] # An array of arguments attached to the entity
 local function AddArguments(Entity, Arguments)
 	local Lookup = Entity.Lookup
 	local Count  = Entity.Count
@@ -43,6 +55,10 @@ local function AddArguments(Entity, Arguments)
 	return List
 end
 
+--- Registers a class as a spawnable entity class
+--- @param Class string The class to register
+--- @param Function fun(Player:entity, Pos:vector, Ang:angle, Data:table):Entity A function defining how to spawn your class (This should be your MakeACF_<something> function)
+--- @param ... any #A vararg of arguments to attach to the entity
 function Entities.Register(Class, Function, ...)
 	if not isstring(Class) then return end
 	if not isfunction(Function) then return end
@@ -56,6 +72,10 @@ function Entities.Register(Class, Function, ...)
 	duplicator.RegisterEntityClass(Class, Function, "Pos", "Angle", "Data", unpack(List))
 end
 
+--- Adds extra arguments to a class which has already been called in Entities.Register  
+--- Should be called after Entities.Register if you want to specify any additional arguments
+--- @param Class string A class previously registered as an entity class
+--- @param ... any #A vararg of arguments
 function Entities.AddArguments(Class, ...)
 	if not isstring(Class) then return end
 
@@ -68,6 +88,9 @@ function Entities.AddArguments(Class, ...)
 	end
 end
 
+--- Returns an array of the entity's arguments
+--- @param Class string The entity class to get arguments from
+--- @return any[] # An array of arguments attached to the entity
 function Entities.GetArguments(Class)
 	if not isstring(Class) then return end
 
@@ -89,6 +112,15 @@ do -- Spawning and updating
 	local hook = hook
 	local undo = undo
 
+	--- Spawns an entity with the given parameters
+	--- Internally calls the class' Spawn method
+	--- @param Class string The class of entity to spawn
+	--- @param Player entity The player creating the entity
+	--- @param Position vector The position to create the entity at
+	--- @param Angles angle The angles to create the entity at
+	--- @param Data table The data to pass into the entity's spawn function
+	--- @param NoUndo boolean Whether the entity is added to the undo list (can be z keyed)
+	--- @return boolean, table? # Whether the spawning was successful and the reason why
 	function Entities.Spawn(Class, Player, Position, Angles, Data, NoUndo)
 		if not isstring(Class) then return false end
 
@@ -118,6 +150,11 @@ do -- Spawning and updating
 		return true, Entity
 	end
 
+	--- Triggers the update function of an entity  
+	--- Internally calls the ENT:Update(Data) metamethod that's implemented on all entities
+	--- @param Entity table The entity to update
+	--- @param Data table The data to pass into the entity on update
+	--- @return boolean, string # Whether the update was successful and the reason why
 	function Entities.Update(Entity, Data)
 		if not IsValid(Entity) then return false, "Can't update invalid entities." end
 		if not isfunction(Entity.Update) then return false, "This entity does not support updating." end

lua/acf/core/networking/data_vars/data_vars_cl.lua

@@ -122,6 +122,11 @@ do -- Client data getter functions
 end
 
 do -- Client data setter function
+	--- Sets a client data var and networks it to the server.
+	--- Internally calls the ACF_OnClientDataUpdate hook
+	--- @param Key string The key of the datavar
+	--- @param Value any The value the datavar
+	--- @param Forced boolean Whether to send regardless of if the value has changed
 	function ACF.SetClientData(Key, Value, Forced)
 		if not isstring(Key) then return end
 
@@ -138,11 +143,18 @@ do -- Client data setter function
 end
 
 do -- Server data setter function
+	--- Proposes changes to server datavars and networks them to server.
+	--- Internally calls the ACF_OnServerDataUpdate hook.
+	--- @param Key string The key of the datavar
+	--- @param Value any The value of the datavar
+	--- @param Forced boolean Whether to send regardless of if the value has changed
 	function ACF.SetServerData(Key, Value, Forced)
 		if not isstring(Key) then return end
 
 		local Player = LocalPlayer()
 
+		-- Check if the client is allowed to set things on the server
+		-- (Usually restricted to super admins and server owners)
 		if not ACF.CanSetServerData(Player) then return end
 
 		Value = Value or false

lua/acf/core/networking/data_vars/data_vars_sh.lua

@@ -1,5 +1,8 @@
 local ACF = ACF
 
+--- Returns whether a client is allowed to set a server datavars
+--- @param Player table The player entity to check
+--- @return boolean # Whether the player can set server datavars
 function ACF.CanSetServerData(Player)
 	if not IsValid(Player) then return true end -- No player, probably the server
 	if Player:IsSuperAdmin() then return true end

lua/acf/core/networking/data_vars/data_vars_sv.lua

@@ -178,11 +178,18 @@ do -- Client data getter functions
 		return ACF.CheckString(Value, "")
 	end
 
+	--- When called, returns all the table storing all of the client's datavars
 	ACF.GetClientData = GetData
 	ACF.GetClientRaw = GetData
 end
 
 do -- Server data setter function
+	--- Sets a server datavar and networks it to the client
+	--- The server cannot modify the client because we don't want ACF to natively support servers modifying the client
+	--- Internally calls the ACF_OnServerDataUpdate hook
+	--- @param Key string The key of the datavar
+	--- @param Value any The value the datavar
+	--- @param Forced boolean Whether to send regardless of difference checks
 	function ACF.SetServerData(Key, Value, Forced)
 		if not isstring(Key) then return end
 

lua/acf/core/utilities/util_sh.lua

@@ -356,12 +356,20 @@ do -- ACF.GetHitAngle
 end
 
 do -- Native type verification functions
+	--- Returns the numerical representation of a value or a default of this type
+	--- @param Value number The input to be converted to a number
+	--- @param Default number The default value if the input canno tbe made into a number
+	--- @return number # The numerical result
 	function ACF.CheckNumber(Value, Default)
 		if not Value then return Default end
 
 		return tonumber(Value) or Default
 	end
 
+	--- Returns the string representation of a value or a default of this type
+	--- @param Value string The input to be converted to a string
+	--- @param Default string The default value if the input cannot be made into a string
+	--- @return string # The string result
 	function ACF.CheckString(Value, Default)
 		if Value == nil then return Default end
 

lua/acf/core/validation_sv.lua

@@ -224,6 +224,7 @@ function ACF.Activate(Entity, Recalc)
 	Entity.ACF.Type    = ACF.GetEntityType(Entity)
 	Entity.ACF.PhysObj = PhysObj
 
+	-- Note that if the entity has its own ENT:ACF_Activate(Recalc) function, the rest of the code after this block won't be ran (instead the function should specify the rest)
 	if Entity.ACF_Activate then
 		Entity:ACF_Activate(Recalc)
 		return

lua/acf/menu/tool_functions.lua

@@ -372,6 +372,10 @@ do -- Clientside Tool interaction
 		local Key = "ToolMode:%s"
 		local Value = "%s:%s"
 
+		--- Sets and networks to the server, the current state of a tool, its stage and its operation. 
+		--- @param Tool string The name of the tool (e.g. "acf_menu"/"acf_copy")
+		--- @param Stage string The stage of the tool (e.g. "Spawner"/"Main")
+		--- @param Op string The operation of the tool (e.g. "Weapon"/"Sensor"/etc.)
 		function ACF.SetToolMode(Tool, Stage, Op)
 			if not isstring(Tool) then return end
 			if not isstring(Stage) then return end
@@ -593,13 +597,21 @@ do -- Generic Spawner/Linker operation creator
 		end
 	end
 
+	--- Creates a menu operation  
+	--- Mostly serves as a wrapper for (https://wiki.facepunch.com/gmod/Tool_Information_Display)  
+	--- Internally links the helpers SpawnEntity and SelectEntity to your left and right mouse  
+	--- To actually define an entity's linking or spawn behaviour, use the entity files (e.g. init.lua)  
+	--- @param Name string The name of the link type performed by the toolgun (e.g. Weapon, Engine, etc.)
+	--- @param Primary string The type of the entity to be spawned on left click (purely aesthetical)
+	--- @param Secondary string The type of entity to be spawned on shift + right click (purely aesthetical)
 	function ACF.CreateMenuOperation(Name, Primary, Secondary)
 		if not isstring(Name) then return end
 		if not isstring(Primary) then return end
 
 		Secondary = ACF.CheckString(Secondary)
 
 		do -- Spawner stuff
+			-- These basically setup the tool information display you see on the top left of your screen
 			ACF.RegisterOperation("acf_menu", "Spawner", Name, {
 				OnLeftClick  = SpawnEntity,
 				OnRightClick = function(Tool, Trace)