docs: improve emmy lua annotations

commander-stdout
sammyette 2022-12-20 20:59:55 -04:00
parent 5dc3b7d337
commit a105b8e38d
Signed by: sammyette
GPG Key ID: 904FC49417B44DCD
13 changed files with 92 additions and 35 deletions

View File

@ -92,8 +92,9 @@ func (a *aliasModule) Loader(rtm *rt.Runtime) *rt.Table {
func _hlalias() {}
// #interface aliases
// list()
// Get a table of all aliases.
// list() -> aliases (table)
// Get a table of all aliases, with string keys as the alias and the value as the command.
// @returns table<string, string>
func (a *aliasModule) luaList(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
aliasesList := rt.NewTable()
for k, v := range a.All() {
@ -121,9 +122,10 @@ func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// #interface aliases
// resolve(alias)
// resolve(alias) -> command (string)
// Tries to resolve an alias to its command.
// --- @param alias string
// --- @returns string
func (a *aliasModule) luaResolve(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err

16
api.go
View File

@ -184,11 +184,13 @@ func unsetVimMode() {
util.SetField(l, hshMod, "vimMode", rt.NilValue)
}
// run(cmd, returnOut) -> exitCode, stdout, stderr
// run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)
// Runs `cmd` in Hilbish's sh interpreter.
// If returnOut is true, the outputs of `cmd` will be returned as the 2nd and
// 3rd values instead of being outputted to the terminal.
// --- @param cmd string
// --- @param returnOut boolean
// --- @returns number, string, string
func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -238,11 +240,11 @@ func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// read(prompt) -> input
// read(prompt) -> input (string)
// Read input from the user, using Hilbish's line editor/input reader.
// This is a separate instance from the one Hilbish actually uses.
// Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen)
// --- @param prompt string|nil
// --- @param prompt? string
// --- @returns string|nil
func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
luaprompt := c.Arg(0)
@ -278,7 +280,7 @@ These will be formatted and replaced with the appropriate values.
`%u` - Name of current user
`%h` - Hostname of device
--- @param str string
--- @param typ string|nil Type of prompt, being left or right. Left by default.
--- @param typ? string Type of prompt, being left or right. Left by default.
*/
func hlprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
err := c.Check1Arg()
@ -447,7 +449,7 @@ func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// Returns a `timer` object (see `doc timers`).
// --- @param cb function
// --- @param time number
// --- @return table
// --- @returns table
func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil {
return nil, err
@ -536,7 +538,7 @@ func hlprependPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// which(name)
// Checks if `name` is a valid command
// --- @param binName string
// --- @param name string
func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -621,7 +623,7 @@ func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// as the text for the hint. This is by default a shim. To set hints,
// override this function with your custom handler.
// --- @param line string
// --- @param pos int
// --- @param pos number
func hlhinter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.Next(), nil
}

View File

@ -193,6 +193,8 @@ func completionLoader(rtm *rt.Runtime) *rt.Table {
// handler(line, pos)
// The handler function is the callback for tab completion in Hilbish.
// You can check the completions doc for more info.
// --- @param line string
// --- @param pos string
func completionHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.Next(), nil
}
@ -202,6 +204,10 @@ func completionHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// Calls a completer function. This is mainly used to call
// a command completer, which will have a `name` in the form
// of `command.name`, example: `command.git`
// --- @param name string
// --- @param query string
// --- @param ctx string
// --- @param fields table
func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(4); err != nil {
return nil, err
@ -244,6 +250,9 @@ func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface completions
// files(query, ctx, fields)
// Returns file completion candidates based on the provided query.
// --- @param query string
// --- @param ctx string
// --- @param fields table
func luaFileComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
query, ctx, fds, err := getCompleteParams(t, c)
if err != nil {
@ -263,6 +272,9 @@ func luaFileComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface completions
// bins(query, ctx, fields)
// Returns binary/executale completion candidates based on the provided query.
// --- @param query string
// --- @param ctx string
// --- @param fields table
func luaBinaryComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
query, ctx, fds, err := getCompleteParams(t, c)
if err != nil {

View File

@ -21,8 +21,8 @@ Catches a hook with `name`. Runs the `cb` when it is thrown
### catchOnce(name, cb)
Same as catch, but only runs the `cb` once and then removes the hook
### hooks(name) -> {cb, cb...}
Returns a table with hooks on the event with `name`.
### hooks(name) -> {}
Returns a table with hooks (callback functions) on the event with `name`.
### release(name, catcher)
Removes the `catcher` for the event with `name`

View File

@ -31,16 +31,21 @@ filepath.Dir
Glob all files and directories that match the pattern.
For the rules, see Go's filepath.Glob
### join(paths...)
### join(...)
Takes paths and joins them together with the OS's
directory separator (forward or backward slash).
### mkdir(name, recursive)
Makes a directory called `name`. If `recursive` is true, it will create its parent directories.
### readdir(dir)
Returns a table of files in `dir`
### readdir(dir) -> {}
Returns a table of files in `dir`.
### stat(path)
Returns info about `path`
### stat(path) -> {}
Returns a table of info about the `path`.
It contains the following keys:
name (string) - Name of the path
size (number) - Size of the path
mode (string) - Permission mode in an octal format string (with leading 0)
isDir (boolean) - If the path is a directory

View File

@ -45,6 +45,8 @@ func editorInsert(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface editor
// setVimRegister(register, text)
// Sets the vim register at `register` to hold the passed text.
// --- @param register string
// --- @param text string
func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -68,6 +70,7 @@ func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface editor
// getVimRegister(register)
// Returns the text that is at the register.
// --- @param register string
func editorGetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err

View File

@ -12,9 +12,9 @@ function bait.catch(name, cb) end
--- @param cb function
function bait.catchOnce(name, cb) end
--- Returns a table with hooks on the event with `name`.
--- Returns a table with hooks (callback functions) on the event with `name`.
--- @param name string
--- @returns table
--- @returns table<function>
function bait.hooks(name) end
--- Removes the `catcher` for the event with `name`

View File

@ -16,28 +16,37 @@ function fs.cd(dir) end
--- Returns the directory part of `path`. For the rules, see Go's
--- filepath.Dir
--- @param path string
function fs.dir(path) end
--- Glob all files and directories that match the pattern.
--- For the rules, see Go's filepath.Glob
--- @param pattern string
function fs.glob(pattern) end
--- Takes paths and joins them together with the OS's
--- directory separator (forward or backward slash).
function fs.join(paths...) end
--- @vararg any
function fs.join(...) end
--- Makes a directory called `name`. If `recursive` is true, it will create its parent directories.
--- @param name string
--- @param recursive boolean
function fs.mkdir(name, recursive) end
--- Returns a table of files in `dir`
--- Returns a table of files in `dir`.
--- @param dir string
--- @return table
function fs.readdir(dir) end
--- Returns info about `path`
--- Returns a table of info about the `path`.
--- It contains the following keys:
--- name (string) - Name of the path
--- size (number) - Size of the path
--- mode (string) - Permission mode in an octal format string (with leading 0)
--- isDir (boolean) - If the path is a directory
--- @param path string
--- @returns table
function fs.stat(path) end
return fs

View File

@ -296,10 +296,10 @@ func (b *Bait) brelease(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.Next(), nil
}
// hooks(name) -> {cb, cb...}
// Returns a table with hooks on the event with `name`.
// hooks(name) -> {}
// Returns a table with hooks (callback functions) on the event with `name`.
// --- @param name string
// --- @returns table
// --- @returns table<function>
func (b *Bait) bhooks(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err

View File

@ -93,9 +93,15 @@ func fmkdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.Next(), err
}
// stat(path)
// Returns info about `path`
// stat(path) -> {}
// Returns a table of info about the `path`.
// It contains the following keys:
// name (string) - Name of the path
// size (number) - Size of the path
// mode (string) - Permission mode in an octal format string (with leading 0)
// isDir (boolean) - If the path is a directory
// --- @param path string
// --- @returns table
func fstat(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -119,8 +125,8 @@ func fstat(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.PushingNext1(t.Runtime, rt.TableValue(statTbl)), nil
}
// readdir(dir)
// Returns a table of files in `dir`
// readdir(dir) -> {}
// Returns a table of files in `dir`.
// --- @param dir string
// --- @return table
func freaddir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
@ -181,6 +187,7 @@ func fbasename(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// dir(path)
// Returns the directory part of `path`. For the rules, see Go's
// filepath.Dir
// --- @param path string
func fdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -196,6 +203,7 @@ func fdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// glob(pattern)
// Glob all files and directories that match the pattern.
// For the rules, see Go's filepath.Glob
// --- @param pattern string
func fglob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -219,9 +227,10 @@ func fglob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.PushingNext(t.Runtime, rt.TableValue(luaMatches)), nil
}
// join(paths...)
// join(...)
// Takes paths and joins them together with the OS's
// directory separator (forward or backward slash).
// --- @vararg any
func fjoin(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
strs := make([]string, len(c.Etc()))
for i, v := range c.Etc() {

13
job.go
View File

@ -384,8 +384,10 @@ func jobUserData(j *job) *rt.UserData {
}
// #interface jobs
// get(id)
// get(id) -> job (Job/Table)
// Get a job object via its ID.
// --- @param id number
// --- @returns Job
func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
j.mu.RLock()
defer j.mu.RUnlock()
@ -409,6 +411,9 @@ func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface jobs
// add(cmdstr, args, execPath)
// Adds a new job to the job table. Note that this does not immediately run it.
// --- @param cmdstr string
// --- @param args table
// --- @param execPath string
func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(3); err != nil {
return nil, err
@ -439,8 +444,9 @@ func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// #interface jobs
// all()
// all() -> jobs (table<Job/Table>)
// Returns a table of all job objects.
// --- @returns table<Job>
func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
j.mu.RLock()
defer j.mu.RUnlock()
@ -474,8 +480,9 @@ func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// #interface jobs
// last() -> Job
// last() -> job (Job/Table)
// Returns the last added job from the table.
// --- @returns Job
func (j *jobHandler) luaLastJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
j.mu.RLock()
defer j.mu.RUnlock()

View File

@ -32,12 +32,14 @@ func runnerModeLoader(rtm *rt.Runtime) *rt.Table {
// which will be used to execute all interactive input.
// In normal cases, neither callbacks should be overrided by the user,
// as the higher level functions listed below this will handle it.
// --- @param cb function
func _runnerMode() {}
// #interface runner
// sh(cmd)
// Runs a command in Hilbish's shell script interpreter.
// This is the equivalent of using `source`.
// --- @param cmd string
func shRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -65,6 +67,7 @@ func shRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// lua(cmd)
// Evaluates `cmd` as Lua input. This is the same as using `dofile`
// or `load`, but is appropriated for the runner interface.
// --- @param cmd string
func luaRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err

View File

@ -64,7 +64,10 @@ func (th *timersModule) get(id int) *timer {
// #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).
// The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
// --- @param type number
// --- @param time number
// --- @param callback function
func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(3); err != nil {
return nil, err
@ -88,8 +91,10 @@ func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// #interface timers
// get(id)
// get(id) -> timer (Timer/Table)
// Retrieves a timer via its ID.
// --- @param id number
// --- @returns Timer
func (th *timersModule) luaGet(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err