@@ -11,29 +11,32 @@ local util = require("overseer.util")
1111local STATUS = constants .STATUS
1212
1313--- @class overseer.Task
14- --- @field id number
15- --- @field result ? table
16- --- @field metadata table
17- --- @field default_component_params table
18- --- @field status overseer.Status
19- --- @field cmd string | string[]
20- --- @field cwd string
21- --- @field env ? table<string , string>
22- --- @field strategy_defn string | table
23- --- @field strategy overseer.Strategy
24- --- @field name string
14+ --- @opaque
15+ --- @field id integer Unique ID for this task
16+ --- @field result ? table<string , any> For successful tasks , arbitrary key-value mapping of data produced by components
17+ --- @field metadata table<string , any> Arbitrary key-value mapping passed by the user during construction
18+ --- @field private default_component_params table<string , any>
19+ --- @field status overseer.Status Current task status
20+ --- @field cmd string | string[] Command to run. If it ' s a string it is run in the shell
21+ --- @field cwd string Working directory the task is run in
22+ --- @field env ? table<string , string> Additional environment variables for the task
23+ --- @field private strategy_defn string | table
24+ --- @field private strategy overseer.Strategy
25+ --- @field name string Name of the task
2526--- @field ephemeral boolean Indicates that this task was generated indirectly (e.g. with run_after )
2627--- @field source ? overseer.Caller If this task was created by wrapping jobstart /vim.system , this contains information about the callsite
27- --- @field exit_code ? number
28- --- @field components overseer.Component[]
28+ --- @field exit_code ? integer Exit code of the task process
29+ --- @field private components overseer.Component[]
2930--- @field parent_id ? integer ID of parent task. Used only to visually group tasks in the task list
30- --- @field time_start ? integer
31- --- @field time_end ? integer
31+ --- @field time_start ? integer Timestamp when the task was started ( os.time ())
32+ --- @field time_end ? integer Timestamp when the task ended ( os.time ())
3233--- @field private from_template ? overseer.TemplateSource
3334--- @field private prev_bufnr ? integer
34- --- @field private _subscribers table<string , function []>
35+ --- @field private _subscribers table<string , overseer.TaskEventHandler []>
3536local Task = {}
3637
38+ --- @alias overseer.TaskEventHandler fun ( task : overseer.Task , ... : any ): nil | boolean
39+
3740local next_id = 1
3841
3942--- @class (exact ) overseer.TaskDefinition
289292--- @param event string
290293--- @param callback fun ( task : overseer.Task , ... : any ): nil | boolean Callback can return a truthy value to unsubscribe itself
291294--- @note
292- --- Listeners cannot be serialized, so will not be saved when saving task to disk and will not be
293- --- copied when cloning the task.
295+ --- Listeners cannot be serialized, so will not be saved when saving task
296+ --- to disk and will not be copied when cloning the task.
294297function Task :subscribe (event , callback )
295298 if not self ._subscribers [event ] then
296299 self ._subscribers [event ] = {}
0 commit comments