From 3cefcfffe30618fa4e26a0d0766c8e4d9f8dee70 Mon Sep 17 00:00:00 2001 From: Lucas Schwiderski Date: Wed, 16 Jun 2021 20:20:09 +0200 Subject: [PATCH] doc(g.timer): Improve documentation for helpers Clarifies behaviour for the convenience constructor functions. Signed-off-by: Lucas Schwiderski --- lib/gears/timer.lua | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index 27ef00d6..fce8140a 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -194,13 +194,17 @@ function timer.new(args) return ret end ---- Create a timeout for calling some callback function. --- When the callback function returns true, it will be called again after the --- same timeout. If false is returned, no more calls will be done. If the --- callback function causes an error, no more calls are done. +--- Create a simple timer for calling the `callback` function continuously. +-- +-- This is a small wrapper around `gears.timer`, that creates a timer based on +-- `callback`. +-- The timer will run continuously and call `callback` every `timeout` seconds. +-- It is stopped when `callback` returns `false`, when `callback` throws an +-- error or when `stop` is called on the return value. +-- -- @tparam number timeout Timeout in seconds (e.g. 1.5). -- @tparam function callback Function to run. --- @treturn timer The timer object that was set up. +-- @treturn timer The new timer object. -- @staticfct gears.timer.start_new -- @see gears.timer.weak_start_new function timer.start_new(timeout, callback) @@ -215,14 +219,18 @@ function timer.start_new(timeout, callback) return t end ---- Create a timeout for calling some callback function. --- This function is almost identical to `gears.timer.start_new`. The only difference --- is that this does not prevent the callback function from being garbage --- collected. After the callback function was collected, the timer returned --- will automatically be stopped. +--- Create a simple timer for calling the `callback` function continuously. +-- +-- This function is almost identical to `gears.timer.start_new`. The only +-- difference is that this does not prevent the callback function from being +-- garbage collected. +-- In addition to the conditions in `gears.timer.start_new`, +-- this timer will also stop if `callback` was garbage collected since the +-- previous run. +-- -- @tparam number timeout Timeout in seconds (e.g. 1.5). -- @tparam function callback Function to start. --- @treturn timer The timer object that was set up. +-- @treturn timer The new timer object. -- @staticfct gears.timer.weak_start_new -- @see gears.timer.start_new function timer.weak_start_new(timeout, callback)