docs: improve emmy lua annotations

aliases.go

@@ -92,8 +92,9 @@ func (a *aliasModule) Loader(rtm *rt.Runtime) *rt.Table {
 func _hlalias() {}
 
 // #interface aliases
-// list()
+// list() -> aliases (table)
-// Get a table of all aliases.
+// 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

api.go

@@ -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
 }

complete.go

@@ -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 {

docs/api/bait.md

@@ -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...}
+### hooks(name) -> {}
-Returns a table with hooks on the event with `name`.
+Returns a table with hooks (callback functions) on the event with `name`.
 
 ### release(name, catcher)
 Removes the `catcher` for the event with `name`

docs/api/fs.md

@@ -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)
+### readdir(dir) -> {}
-Returns a table of files in `dir`
+Returns a table of files in `dir`.
 
-### stat(path)
+### stat(path) -> {}
-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
 

editor.go

@@ -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

emmyLuaDocs/bait.lua

@@ -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`

emmyLuaDocs/fs.lua

@@ -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

golibs/bait/bait.go

@@ -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...}
+// hooks(name) -> {}
-// 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>
 func (b *Bait) bhooks(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err

golibs/fs/fs.go

@@ -93,9 +93,15 @@ func fmkdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), err
 }
 
-// stat(path)
+// stat(path) -> {}
-// 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
 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)
+// readdir(dir) -> {}
-// Returns a table of files in `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() {

job.go

@@ -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()

runnermode.go

@@ -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

timerhandler.go

@@ -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