From 98eddf90043eaa9a0ff0705d72fc5c3632aa689e Mon Sep 17 00:00:00 2001
From: sammyette <torchedsammy@gmail.com>
Date: Wed, 14 Dec 2022 18:44:02 -0400
Subject: [PATCH] docs: add hilbish.timers interface docs

---
 docs/api/hilbish/hilbish.jobs.md   |  3 ++-
 docs/api/hilbish/hilbish.timers.md | 15 +++++++++++++++
 emmyLuaDocs/hilbish.lua            | 10 ++++++++++
 nature/runner.lua                  |  1 +
 timer.go                           |  4 ++++
 timerhandler.go                    | 10 ++++++++++
 6 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md
index e79ed52..49962e6 100644
--- a/docs/api/hilbish/hilbish.jobs.md
+++ b/docs/api/hilbish/hilbish.jobs.md
@@ -5,7 +5,8 @@ layout: apidoc
 ---
 
 ## Introduction
- Manage interactive jobs in Hilbish via Lua.
+
+Manage interactive jobs in Hilbish via Lua.
 
 Jobs are the name of background tasks/commands. A job can be started via
 interactive usage or with the functions defined below for use in external runners.
diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md
index b6ca5c2..2b29709 100644
--- a/docs/api/hilbish/hilbish.timers.md
+++ b/docs/api/hilbish/hilbish.timers.md
@@ -9,7 +9,22 @@ The timers interface si one to easily set timeouts and intervals
 to run functions after a certain time or repeatedly without using
 odd tricks.
 
+## Object properties
+- `type`: What type of timer it is
+- `running`: If the timer is running
+- `duration`: The duration in milliseconds that the timer will run
+
 ## Functions
+### start()
+Starts a timer.
+
 ### stop()
 Stops a timer.
 
+### create(type, time, callback)
+Creates a timer that runs based on the specified `time` in milliseconds.
+The `type` can either be interval (value of 0) or timeout (value of 1).
+
+### get(id)
+Retrieves a timer via its ID.
+
diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua
index 74eb01c..ef417f0 100644
--- a/emmyLuaDocs/hilbish.lua
+++ b/emmyLuaDocs/hilbish.lua
@@ -155,6 +155,9 @@ function hilbish.jobs.stop() end
 --- This is the equivalent of using `source`.
 function hilbish.runner.sh(cmd) end
 
+--- Starts a timer.
+function hilbish.timers:start() end
+
 --- Stops a timer.
 function hilbish.timers:stop() end
 
@@ -199,4 +202,11 @@ function hilbish.history.get(idx) end
 --- @returns number
 function hilbish.history.size() end
 
+--- Creates a timer that runs based on the specified `time` in milliseconds.
+--- The `type` can either be interval (value of 0) or timeout (value of 1).
+function hilbish.timers.create(type, time, callback) end
+
+--- Retrieves a timer via its ID.
+function hilbish.timers.get(id) end
+
 return hilbish
diff --git a/nature/runner.lua b/nature/runner.lua
index e155f63..9b62ad1 100644
--- a/nature/runner.lua
+++ b/nature/runner.lua
@@ -1,3 +1,4 @@
+--- hilbish.runner
 local currentRunner = 'hybrid'
 local runners = {}
 
diff --git a/timer.go b/timer.go
index f59749e..be8f270 100644
--- a/timer.go
+++ b/timer.go
@@ -73,6 +73,10 @@ func (t *timer) stop() error {
 	return nil
 }
 
+// #interface timers
+// #member
+// start()
+// Starts a timer.
 func timerStart(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
diff --git a/timerhandler.go b/timerhandler.go
index b03435b..92947e1 100644
--- a/timerhandler.go
+++ b/timerhandler.go
@@ -61,6 +61,10 @@ func (th *timersModule) get(id int) *timer {
 	return th.timers[id]
 }
 
+// #interface timers
+// create(type, time, callback)
+// Creates a timer that runs based on the specified `time` in milliseconds.
+// The `type` can either be interval (value of 0) or timeout (value of 1).
 func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(3); err != nil {
 		return nil, err
@@ -83,6 +87,9 @@ func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, rt.UserDataValue(tmr.ud)), nil
 }
 
+// #interface timers
+// get(id)
+// Retrieves a timer via its ID.
 func (th *timersModule) luaGet(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -101,6 +108,9 @@ func (th *timersModule) luaGet(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface timers
+// #property type What type of timer it is
+// #property running If the timer is running
+// #property duration The duration in milliseconds that the timer will run
 // timeout and interval API
 // The timers interface si one to easily set timeouts and intervals
 // to run functions after a certain time or repeatedly without using