From 1226801a78b1842b5c641cc851f0b9a0e6dda2bc Mon Sep 17 00:00:00 2001 From: sammyette Date: Sat, 7 Jan 2023 12:57:34 -0400 Subject: [PATCH] docs: document timer type, update generated docs --- docs/api/hilbish/hilbish.jobs.md | 45 +++++++++++++++--------------- docs/api/hilbish/hilbish.timers.md | 31 ++++++++++---------- timer.go | 5 ++++ timerhandler.go | 12 +++----- 4 files changed, 49 insertions(+), 44 deletions(-) diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md index 80308f7..a8f48aa 100644 --- a/docs/api/hilbish/hilbish.jobs.md +++ b/docs/api/hilbish/hilbish.jobs.md @@ -14,29 +14,7 @@ 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. -## Types -### Job -Job Type. -#### Properties -- `cmd`: The user entered command string for the job. -- `running`: Whether the job is running or not. -- `id`: The ID of the job in the job table -- `pid`: The Process ID -- `exitCode`: The last exit code of the job. -- `stdout`: The standard output of the job. This just means the normal logs of the process. -- `stderr`: The standard error stream of the process. This (usually) includes error messages of the job. - ## Functions -### background() -Puts a job in the background. This acts the same as initially running a job. - -### foreground() -Puts a job in the foreground. This will cause it to run like it was -executed normally and wait for it to complete. - -### start() -Starts running the job. - ### stop() Stops the job from running. @@ -55,3 +33,26 @@ Get a job object via its ID. ### last() -> Job Returns the last added job from the table. +## Types +## Job +Job Type. +### Properties +- `cmd`: The user entered command string for the job. +- `running`: Whether the job is running or not. +- `id`: The ID of the job in the job table +- `pid`: The Process ID +- `exitCode`: The last exit code of the job. +- `stdout`: The standard output of the job. This just means the normal logs of the process. +- `stderr`: The standard error stream of the process. This (usually) includes error messages of the job. + +### Methods +#### background() +Puts a job in the background. This acts the same as initially running a job. + +#### foreground() +Puts a job in the foreground. This will cause it to run like it was +executed normally and wait for it to complete. + +#### start() +Starts running the job. + diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md index 0173023..b847041 100644 --- a/docs/api/hilbish/hilbish.timers.md +++ b/docs/api/hilbish/hilbish.timers.md @@ -22,35 +22,38 @@ All functions documented with the `Timer` type refer to a Timer object. An example of usage: ``` -local t = hilbish.timers.create(1, 5000, function() +local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function() print 'hello!' end) -t:stop() -print(t.running, t.duration, t.type) t:start() +print(t.running) // true ``` ## Interface fields - `INTERVAL`: Constant for an interval timer type - `TIMEOUT`: Constant for a timeout timer type -## Object properties +## Functions +### create(type, time, callback) -> Timer +Creates a timer that runs based on the specified `time` in milliseconds. +The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` + +### get(id) -> Timer +Retrieves a timer via its ID. + +## Types +## Timer +Timer type. +### 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() +### Methods +#### start() Starts a timer. -### stop() +#### 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 `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` - -### get(id) -> timer (Timer/Table) -Retrieves a timer via its ID. - diff --git a/timer.go b/timer.go index be8f270..8a5e92f 100644 --- a/timer.go +++ b/timer.go @@ -15,6 +15,11 @@ const ( timerTimeout ) +// #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 +// Timer type. type timer struct{ id int typ timerType diff --git a/timerhandler.go b/timerhandler.go index df33d36..0cb4197 100644 --- a/timerhandler.go +++ b/timerhandler.go @@ -62,7 +62,7 @@ func (th *timersModule) get(id int) *timer { } // #interface timers -// create(type, time, callback) +// create(type, time, callback) -> @Timer // Creates a timer that runs based on the specified `time` in milliseconds. // The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` // --- @param type number @@ -91,7 +91,7 @@ func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // #interface timers -// get(id) -> timer (Timer/Table) +// get(id) -> @Timer // Retrieves a timer via its ID. // --- @param id number // --- @returns Timer @@ -115,9 +115,6 @@ func (th *timersModule) luaGet(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) { // #interface timers // #field INTERVAL Constant for an interval timer type // #field TIMEOUT Constant for a timeout timer type -// #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 /* If you ever want to run a piece of code on a timed interval, or want to wait @@ -134,13 +131,12 @@ All functions documented with the `Timer` type refer to a Timer object. An example of usage: ``` -local t = hilbish.timers.create(1, 5000, function() +local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function() print 'hello!' end) -t:stop() -print(t.running, t.duration, t.type) t:start() +print(t.running) // true ``` */ func (th *timersModule) loader(rtm *rt.Runtime) *rt.Table {