From 9e1ec1641cb1fbaa76894f34f8ac4d8d354cebf1 Mon Sep 17 00:00:00 2001 From: sammyette Date: Tue, 7 Feb 2023 18:18:03 -0400 Subject: [PATCH] docs: fix return types for functions (closes #229) --- complete.go | 9 +++++---- editor.go | 4 ++-- golibs/bait/bait.go | 4 ++-- golibs/fs/fs.go | 17 +++++++++++------ rl.go | 6 +++++- 5 files changed, 25 insertions(+), 15 deletions(-) diff --git a/complete.go b/complete.go index 3850c65..51b426f 100644 --- a/complete.go +++ b/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 diff --git a/editor.go b/editor.go index 282d6a6..3038f07 100644 --- a/editor.go +++ b/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() diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index 2dc8fd5..3f3c34e 100644 --- a/golibs/bait/bait.go +++ b/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 diff --git a/golibs/fs/fs.go b/golibs/fs/fs.go index a9750dd..1c1a5ca 100644 --- a/golibs/fs/fs.go +++ b/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() { diff --git a/rl.go b/rl.go index 6356f64..96b8451 100644 --- a/rl.go +++ b/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()