Updated Docs

expcore/async.lua

@@ -1,31 +1,31 @@
 --[[-- Core Module - Async
-    - An extention of task and token to allow a single require to register and run async functions.
-    @core Async
-    @alias Async
+- An extention of task and token to allow a single require to register and run async functions.
+@core Async
+@alias Async
 
-    @usage
-    -- To use Async you must register the allowed functions when the files are loaded, often this will just be giving access to
-    -- some functions within a module if you expect that some parts may be blocked by in game permissions or a custom system you have made
-    -- you may also want to register functions that you want to have a delayed call, such as waiting 2 seconds before printing a message
+@usage
+-- To use Async you must register the allowed functions when the file is loaded, often this will just be giving access to
+-- some functions within a module if you expect that at part may be blocked by in game permissions or a custom system you have made
+-- you may also want to register functions that you want to have a time delay, such as waiting 2 seconds before printing a message
 
-    -- This player.admin is called (command or gui element event) by a player who isnt admin then it will error
-    -- here we register the function to promote the player so that it will run async
-    local promote_player =
-    Async.register(function(player)
-        player.admin = true
-    end)
+-- When player.admin is called (either command or gui element event) by a player who isnt admin then it will error
+-- here we register the function to promote the player so that it will run async and outside the player scope
+local promote_player =
+Async.register(function(player)
+    player.admin = true
+end)
 
-    -- This will allow us to bypass this by running one tick later outside of any player scope
-    Async(promote_player,game.player)
+-- This will allow us to bypass the error by running one tick later outside of any player scope
+Async(promote_player,game.player)
 
-    -- Here we make an sync function that we want to have a delay, note the delay is not defined here
-    local print_message =
-    Async.register(function(player,message)
-        player.print(message)
-    end)
+-- Here we make an sync function that we want to have a delay, note the delay is not defined here
+local print_message =
+Async.register(function(player,message)
+    player.print(message)
+end)
 
-    -- We can then call the async function with a delay using the wait function
-    Async.wait(60,print_message,game.player,'One second has passed!')
+-- We can then call the async function with a delay using the wait function
+Async.wait(60, print_message, game.player, 'One second has passed!')
 
 ]]
 local Task = require 'utils.task' --- @dep utils.task
@@ -39,13 +39,38 @@ Token.register(function(params)
     return func(unpack(params.params))
 end)
 
---- Register a new async function, must called when the file is loaded
--- @tparam function callback the function that will become an async function
+--[[-- Register a new async function, must called when the file is loaded
+@function register
+@tparam function callback the function that can be called as an async function
+@treturn string the uid of the async function which can be passed to Async.run and Async.wait
+
+@usage-- Registering a function to set the admin state of a player
+local set_admin =
+Async.register(function(player, state)
+    if player.valid then
+        player.admin = state
+    end
+end)
+
+@usage-- Registering a function to print to a player
+local print_to_player =
+Async.register(function(player, message)
+    if player.valid then
+        player.print(message)
+    end
+end)
+
+]]
 Async.register = Token.register
 
---- Runs the async function linked to this token, you may supply any number of params as needed
--- @tparam string token the token of the async function you want to run
--- @tparam[opt] any ... the other params that you want to pass to your function
+--[[-- Runs an async function, you may supply any number of arguments as required by that function
+@tparam string token the token of the async function you want to run
+@tparam[opt] any ... the other params that you want to pass to your function
+
+@usage-- Make a player admin regardless of if you are admin
+Async.run(set_admin, player, true)
+
+]]
 function Async.run(token,...)
     Task.queue_task(internal_run, {
         token = token,
@@ -53,10 +78,15 @@ function Async.run(token,...)
     })
 end
 
---- Runs the async function linked to this token after the given number of ticks, you may supply any number of params as needed
--- @tparam number ticks the number of ticks that you want the function to run after
--- @tparam string token the token of the async function you want to run
--- @tparam[opt] any ... the other params that you want to pass to your function
+--[[-- Runs an async function after the given number of ticks, you may supply any number of arguments as required by that function
+@tparam number ticks the number of ticks that you want the function to run after
+@tparam string token the token of the async function you want to run
+@tparam[opt] any ... the other params that you want to pass to your function
+
+@usage-- Print a message to a player after 5 seconds
+Async.wait(300, print_to_player, 'Hello, World!')
+
+]]
 function Async.wait(ticks,token,...)
     Task.set_timeout_in_ticks(ticks, internal_run, {
         token = token,