docs: fix return types for functions (closes #229)

complete.go

@@ -216,10 +216,11 @@ func completionHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface completions
-// call(name, query, ctx, fields)
+// call(name, query, ctx, fields) -> completionGroups (table), prefix (string)
 // 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`
+// of `command.name`, example: `command.git`.
+// You can check `doc completions` for info on the `completionGroups` return value.
 // --- @param name string
 // --- @param query string
 // --- @param ctx string
@@ -264,7 +265,7 @@ func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface completions
-// files(query, ctx, fields)
+// files(query, ctx, fields) -> entries (table), prefix (string)
 // Returns file completion candidates based on the provided query.
 // --- @param query string
 // --- @param ctx string
@@ -286,7 +287,7 @@ func luaFileComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface completions
-// bins(query, ctx, fields)
+// bins(query, ctx, fields) -> entries (table), prefix (string)
 // Returns binary/executale completion candidates based on the provided query.
 // --- @param query string
 // --- @param ctx string

editor.go

@@ -68,7 +68,7 @@ func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface editor
-// getVimRegister(register)
+// getVimRegister(register) -> string
 // Returns the text that is at the register.
 // --- @param register string
 func editorGetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
@@ -87,7 +87,7 @@ func editorGetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface editor
-// getLine()
+// getLine() -> string
 // Returns the current input line.
 func editorGetLine(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	buf := lr.rl.GetLine()

golibs/bait/bait.go

@@ -280,7 +280,7 @@ func (b *Bait) bcatchOnce(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // release(name, catcher)
-// Removes the `catcher` for the event with `name`
+// Removes the `catcher` for the event with `name`.
 // For this to work, `catcher` has to be the same function used to catch
 // an event, like one saved to a variable.
 // --- @param name string
@@ -296,7 +296,7 @@ func (b *Bait) brelease(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
-// hooks(name) -> {}
+// hooks(name) -> table
 // Returns a table with hooks (callback functions) on the event with `name`.
 // --- @param name string
 // --- @returns table<function>

golibs/fs/fs.go

@@ -151,9 +151,10 @@ func freaddir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, rt.TableValue(names)), nil
 }
 
-// abs(path)
+// abs(path) -> string
 // Gives an absolute version of `path`.
 // --- @param path string
+// --- @returns string
 func fabs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	path, err := c.StringArg(0)
 	if err != nil {
@@ -169,9 +170,10 @@ func fabs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, rt.StringValue(abspath)), nil
 }
 
-// basename(path)
+// basename(path) -> string
 // Gives the basename of `path`. For the rules,
 // see Go's filepath.Base
+// --- @returns string
 func fbasename(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -184,10 +186,11 @@ func fbasename(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext(t.Runtime, rt.StringValue(filepath.Base(path))), nil
 }
 
-// dir(path)
+// dir(path) -> string
 // Returns the directory part of `path`. For the rules, see Go's
 // filepath.Dir
 // --- @param path string
+// --- @returns string
 func fdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -200,10 +203,11 @@ func fdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext(t.Runtime, rt.StringValue(filepath.Dir(path))), nil
 }
 
-// glob(pattern)
+// glob(pattern) -> matches (table)
 // Glob all files and directories that match the pattern.
 // For the rules, see Go's filepath.Glob
 // --- @param pattern string
+// --- @returns table
 func fglob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -227,10 +231,11 @@ func fglob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext(t.Runtime, rt.TableValue(luaMatches)), nil
 }
 
-// join(...)
+// join(...) -> string
 // Takes paths and joins them together with the OS's
 // directory separator (forward or backward slash).
-// --- @vararg any
+// --- @vararg string
+// --- @returns string
 func fjoin(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	strs := make([]string, len(c.Etc()))
 	for i, v := range c.Etc() {

rl.go

@@ -263,7 +263,7 @@ func (lr *lineReader) luaAddHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error)
 }
 
 // #interface history
-// size()
+// size() -> number
 // Returns the amount of commands in the history.
 // --- @returns number
 func (lr *lineReader) luaSize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
@@ -288,6 +288,10 @@ func (lr *lineReader) luaGetHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error)
 	return c.PushingNext1(t.Runtime, rt.StringValue(cmd)), nil
 }
 
+// #interface history
+// all() -> table
+// Retrieves all history.
+// --- @returns table
 func (lr *lineReader) luaAllHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	tbl := rt.NewTable()
 	size := lr.fileHist.Len()