Skip to content

Commit

Permalink
Fix the annotations to conform better to lemmy-help
Browse files Browse the repository at this point in the history
  • Loading branch information
@idanarye
idanarye committed Oct 25, 2023
1 parent c699714 commit 68c98ed
Show file tree
Hide file tree
Showing 4 changed files with 58 additions and 33 deletions.
55 changes: 40 additions & 15 deletions doc/channelot.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -87,24 +87,33 @@ M.terminal() *channelot.terminal*
(ChannelotTerminal)


M.terminal_job({opts?}) *channelot.terminal_job*
*channelot.terminal_job*
M.terminal_job({env}, {command}, {opts?})
Start a job on the current buffer, converting it to a terminal

Parameters: ~
{opts?} (ChannelotJobOptions)
{env} (table<string,any>) Environment variables for the command
{command} (string|string[]) The command as a string or as a list of arguments
{opts?} (ChannelotJobOptions)

Returns: ~
(ChannelotJob) @overload fun(command: string|(string[])): ChannelotJob
@overload fun(command: string|(string[]), opts: table): ChannelotJob
(ChannelotJob) @overload fun(command: string|string[]): ChannelotJob
@overload fun(command: string|string[], opts: table): ChannelotJob


M.job({opts?}) *channelot.job*
M.job({env}, {command}, {opts?}) *channelot.job*
Start a job without a terminal attached to it.

Note: this job will not have a PTY, unless `{ pty = true }` is passed in the `opts`.

Parameters: ~
{opts?} (ChannelotJobOptions)
{env} (table<string,any>) Environment variables for the command
{command} (string|string[]) The command as a string or as a list of arguments
{opts?} (ChannelotJobOptions)

Returns: ~
(ChannelotJob) @overload fun(command: string|(string[])): ChannelotJob
@overload fun(command: string|(string[]), opts: table): ChannelotJob
(ChannelotJob) @overload fun(command: string|string[]): ChannelotJob
@overload fun(command: string|string[], opts: table): ChannelotJob


ChannelotTerminal *ChannelotTerminal*
Expand All @@ -113,14 +122,18 @@ ChannelotTerminal *ChannelotTerminal*
{terminal_id} (integer)


ChannelotTerminal:job({opts?}) *ChannelotTerminal:job*
*ChannelotTerminal:job*
ChannelotTerminal:job({env}, {command}, {opts?})
Start a job on a |ChannelotTerminal|.

Parameters: ~
{opts?} (ChannelotJobOptions)
{env} (table<string,any>) Environment variables for the command
{command} (string|string[]) The command as a string or as a list of arguments
{opts?} (ChannelotJobOptions)

Returns: ~
(ChannelotJob) @overload fun(command: string|(string[])): ChannelotJob
@overload fun(command: string|(string[]), opts: table): ChannelotJob
(ChannelotJob) @overload fun(command: string|string[]): ChannelotJob
@overload fun(command: string|string[], opts: table): ChannelotJob


ChannelotTerminal:raw_write({text}) *ChannelotTerminal:raw_write*
Expand Down Expand Up @@ -194,7 +207,11 @@ ChannelotJob *ChannelotJob*
An handle to a Neovim job with functions for controlling it from a Lua coroutine.

Fields: ~
{env} ()
{env} (table<string,any>)
{command} (string|string[])
{pty} (boolean)
{job_id} (integer)
{exit_status?} (integer)


ChannelotJob:wait() *ChannelotJob:wait*
Expand All @@ -217,7 +234,8 @@ ChannelotJob:check({expected_status?}) *ChannelotJob:check*
ChannelotJobIterConfig *ChannelotJobIterConfig*

Fields: ~
{stdout?} ()
{stdout?} ("buffered"|"unbuffered"|"ignore")
{stderr?} ("buffered"|"unbuffered"|"ignore")


ChannelotJob:iter({opts?}) *ChannelotJob:iter*
Expand Down Expand Up @@ -247,7 +265,14 @@ ChannelotJob:close_stdin() *ChannelotJob:close_stdin*
Close the job's standard input.


ChannelotJob:using() *ChannelotJob:using*
ChannelotJob:using({dlg}) *ChannelotJob:using*
Invoke the delegate on the job.

This can be used with third party plugins that add capabilities to Channelot
jobs, or that want to utilize them.

Parameters: ~
{dlg} (fun(job:ChannelotJob))

Returns: ~
(ChannelotJob) The job itself
Expand Down
12 changes: 6 additions & 6 deletions lua/channelot/Job.lua
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ local ChannelotJobOptions

---An handle to a Neovim job with functions for controlling it from a Lua coroutine.
---@class ChannelotJob
---@field env {[string]:any}
---@field env table<string,any>
---@field command string|string[]
---@field pty boolean
---@field job_id integer
Expand Down Expand Up @@ -60,8 +60,8 @@ function ChannelotJob:check(expected_status)
end

---@class ChannelotJobIterConfig
---@field stdout? "'buffered'"|"'unbuffered'"|"'ignore'"
---@field stderr? "'buffered'"|"'unbuffered'"|"'ignore'"
---@field stdout? `"buffered"`|`"unbuffered"`|`"ignore"`
---@field stderr? `"buffered"`|`"unbuffered"`|`"ignore"`

---Iterate over output from the job. Must be called from a Lua coroutine.
---
Expand Down Expand Up @@ -212,10 +212,10 @@ end
---
---This can be used with third party plugins that add capabilities to Channelot
---jobs, or that want to utilize them.
---@param dlg fun(job: ChannelotJob, ...)
---@param dlg fun(job: ChannelotJob)
---@return ChannelotJob # The job itself
function ChannelotJob:using(dlg, ...)
dlg(self, ...)
function ChannelotJob:using(dlg)
dlg(self)
return self
end

Expand Down
8 changes: 4 additions & 4 deletions lua/channelot/Terminal.lua
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@
local ChannelotTerminal = {}

---Start a job on a |ChannelotTerminal|.
---@param env {[string]:any} Environment variables for the command
---@param command string|(string[]) The command as a string or as a list of arguments
---@param env table<string,any> Environment variables for the command
---@param command string|string[] The command as a string or as a list of arguments
---@param opts? ChannelotJobOptions
---@return ChannelotJob
---@overload fun(command: string|(string[])): ChannelotJob
---@overload fun(command: string|(string[]), opts: table): ChannelotJob
---@overload fun(command: string|string[]): ChannelotJob
---@overload fun(command: string|string[], opts: table): ChannelotJob
function ChannelotTerminal:job(env, command, opts)
env, command, opts = require'channelot.util'.normalize_job_arguments(env, command, opts)
local pty = require'channelot.util'.first_non_nil(opts.pty, true)
Expand Down
16 changes: 8 additions & 8 deletions lua/channelot/init.lua
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,12 +103,12 @@ function M.terminal()
end

---Start a job on the current buffer, converting it to a terminal
---@param env {[string]:any} Environment variables for the command
---@param command string|(string[]) The command as a string or as a list of arguments
---@param env table<string,any> Environment variables for the command
---@param command string|string[] The command as a string or as a list of arguments
---@param opts? ChannelotJobOptions
---@return ChannelotJob
---@overload fun(command: string|(string[])): ChannelotJob
---@overload fun(command: string|(string[]), opts: table): ChannelotJob
---@overload fun(command: string|string[]): ChannelotJob
---@overload fun(command: string|string[], opts: table): ChannelotJob
function M.terminal_job(env, command, opts)
env, command, opts = require'channelot.util'.normalize_job_arguments(env, command, opts)
local pty = require'channelot.util'.first_non_nil(opts.pty, true)
Expand Down Expand Up @@ -161,12 +161,12 @@ end
---Start a job without a terminal attached to it.
---
---Note: this job will not have a PTY, unless `{ pty = true }` is passed in the `opts`.
---@param env {[string]:any} Environment variables for the command
---@param command string|(string[]) The command as a string or as a list of arguments
---@param env table<string,any> Environment variables for the command
---@param command string|string[] The command as a string or as a list of arguments
---@param opts? ChannelotJobOptions
---@return ChannelotJob
---@overload fun(command: string|(string[])): ChannelotJob
---@overload fun(command: string|(string[]), opts: table): ChannelotJob
---@overload fun(command: string|string[]): ChannelotJob
---@overload fun(command: string|string[], opts: table): ChannelotJob
function M.job(env, command, opts)
env, command, opts = require'channelot.util'.normalize_job_arguments(env, command, opts)
local pty = require'channelot.util'.first_non_nil(opts.pty, false)
Expand Down

0 comments on commit 68c98ed

Please sign in to comment.