From d921d3f75264cd49b343fb7857aa2766f366cd8b Mon Sep 17 00:00:00 2001 From: sammyette Date: Thu, 30 Nov 2023 22:07:48 -0400 Subject: [PATCH] website(docs/bait): complete documentation --- docs/api/bait.md | 46 +++++++++++++++++++++++++++++++++----------- emmyLuaDocs/bait.lua | 18 ++++++----------- golibs/bait/bait.go | 33 +++++++++++++++++++------------ 3 files changed, 62 insertions(+), 35 deletions(-) diff --git a/docs/api/bait.md b/docs/api/bait.md index cc0eb1a..9f32b25 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -35,11 +35,11 @@ this function will set the user prompt. ## Functions ||| |----|----| -|catch(name, cb)|Catches a hook. This function is used to act on hooks/events.| -|catchOnce(name, cb)|Same as catch, but only runs the `cb` once and then removes the hook| -|hooks(name) -> table|Returns a table with hooks (callback functions) on the event with `name`.| +|catch(name, cb)|Catches an event. This function can be used to act on events.| +|catchOnce(name, cb)|Catches an event, but only once. This will remove the hook immediately after it runs for the first time.| +|hooks(name) -> table|Returns a list of callbacks that are hooked on an event with the corresponding `name`.| |release(name, catcher)|Removes the `catcher` for the event with `name`.| -|throw(name, ...args)|Throws a hook with `name` with the provided `args`| +|throw(name, ...args)|Throws a hook with `name` with the provided `args`.|

@@ -49,7 +49,7 @@ bait.catch(name, cb)

-Catches a hook. This function is used to act on hooks/events. +Catches an event. This function can be used to act on events. #### Parameters @@ -75,9 +75,14 @@ bait.catchOnce(name, cb) -Same as catch, but only runs the `cb` once and then removes the hook +Catches an event, but only once. This will remove the hook immediately after it runs for the first time. #### Parameters -This function has no parameters. +`string` **`name`** +The name of the event + +`function` **`cb`** +The function that will be called when the event is thrown. +
@@ -88,9 +93,11 @@ bait.hooks(name) -> table -Returns a table with hooks (callback functions) on the event with `name`. +Returns a list of callbacks that are hooked on an event with the corresponding `name`. #### Parameters -This function has no parameters. +`string` **`name`** +The name of the function +
@@ -104,8 +111,25 @@ bait.release(name, catcher) Removes the `catcher` for the event with `name`. For this to work, `catcher` has to be the same function used to catch an event, like one saved to a variable. + + #### Parameters -This function has no parameters. +`string` **`name`** +Name of the event the hook is on + +`function` **`catcher`** +Hook function to remove + +#### Example +```lua +local hookCallback = function() print 'hi' end + +bait.catch('event', hookCallback) + +-- a little while later.... +bait.release('event', hookCallback) +-- and now hookCallback will no longer be ran for the event. +````
@@ -116,7 +140,7 @@ bait.throw(name, ...args) -Throws a hook with `name` with the provided `args` +Throws a hook with `name` with the provided `args`. #### Parameters `string` **`name`** The name of the hook. diff --git a/emmyLuaDocs/bait.lua b/emmyLuaDocs/bait.lua index 4b74f82..699d2a5 100644 --- a/emmyLuaDocs/bait.lua +++ b/emmyLuaDocs/bait.lua @@ -2,31 +2,25 @@ local bait = {} ---- Catches a hook. This function is used to act on hooks/events. +--- Catches an event. This function can be used to act on events. --- --- function bait.catch(name, cb) end ---- Same as catch, but only runs the `cb` once and then removes the hook ---- @param name string ---- @param cb function +--- Catches an event, but only once. This will remove the hook immediately after it runs for the first time. function bait.catchOnce(name, cb) end ---- Returns a table with hooks (callback functions) on the event with `name`. ---- @param name string ---- @returns table +--- Returns a list of callbacks that are hooked on an event with the corresponding `name`. function bait.hooks(name) end --- Removes the `catcher` for the event with `name`. --- For this to work, `catcher` has to be the same function used to catch --- an event, like one saved to a variable. ---- @param name string ---- @param catcher function +--- +--- function bait.release(name, catcher) end ---- Throws a hook with `name` with the provided `args` ---- @param name string ---- @vararg any +--- Throws a hook with `name` with the provided `args`. function bait.throw(name, ...args) end return bait diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index 0993c44..b507d2b 100644 --- a/golibs/bait/bait.go +++ b/golibs/bait/bait.go @@ -248,7 +248,7 @@ func handleHook(t *rt.Thread, c *rt.GoCont, name string, catcher *rt.Closure, ar } // catch(name, cb) -// Catches a hook. This function is used to act on hooks/events. +// Catches an event. This function can be used to act on events. // #param name string The name of the hook. // #param cb function The function that will be called when the hook is thrown. /* @@ -270,9 +270,9 @@ func (b *Bait) bcatch(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // catchOnce(name, cb) -// Same as catch, but only runs the `cb` once and then removes the hook -// --- @param name string -// --- @param cb function +// Catches an event, but only once. This will remove the hook immediately after it runs for the first time. +// #param name string The name of the event +// #param cb function The function that will be called when the event is thrown. func (b *Bait) bcatchOnce(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { name, catcher, err := util.HandleStrCallback(t, c) if err != nil { @@ -285,9 +285,9 @@ func (b *Bait) bcatchOnce(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // hooks(name) -> table -// Returns a table with hooks (callback functions) on the event with `name`. -// --- @param name string -// --- @returns table +// Returns a list of callbacks that are hooked on an event with the corresponding `name`. +// #param name string The name of the function +// #returns table func (b *Bait) bhooks(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err @@ -320,8 +320,19 @@ func (b *Bait) bhooks(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // Removes the `catcher` for the event with `name`. // For this to work, `catcher` has to be the same function used to catch // an event, like one saved to a variable. -// --- @param name string -// --- @param catcher function +// #param name string Name of the event the hook is on +// #param catcher function Hook function to remove +/* +#example +local hookCallback = function() print 'hi' end + +bait.catch('event', hookCallback) + +-- a little while later.... +bait.release('event', hookCallback) +-- and now hookCallback will no longer be ran for the event. +#example +*/ func (b *Bait) brelease(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { name, catcher, err := util.HandleStrCallback(t, c) if err != nil { @@ -336,9 +347,7 @@ func (b *Bait) brelease(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // throw(name, ...args) // #param name string The name of the hook. // #param args ...any The arguments to pass to the hook. -// Throws a hook with `name` with the provided `args` -// --- @param name string -// --- @vararg any +// Throws a hook with `name` with the provided `args`. func (b *Bait) bthrow(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { if err := c.Check1Arg(); err != nil { return nil, err