From 65ff0c77ab2e030b5e73e1176782091e7e657c8f Mon Sep 17 00:00:00 2001
From: TorchedSammy <38820196+TorchedSammy@users.noreply.github.com>
Date: Sat, 10 Dec 2022 12:48:15 -0400
Subject: [PATCH] docs: write docs for hilbish.completions

---
 complete.go                             | 16 +++++++++++++++-
 docs/api/hilbish/hilbish.completions.md | 16 ++++++++++++++++
 emmyLuaDocs/hilbish.lua                 | 15 +++++++++++++++
 3 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/complete.go b/complete.go
index 5777c10..7c3f563 100644
--- a/complete.go
+++ b/complete.go
@@ -189,11 +189,19 @@ func completionLoader(rtm *rt.Runtime) *rt.Table {
 	return mod
 }
 
-// left as a shim, might doc in the same way as hilbish functions
+// #interface completions
+// handler(line, pos)
+// The handler function is the callback for tab completion in Hilbish.
+// You can check the completions doc for more info.
 func completionHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
+// #interface completions
+// call(name, query, ctx, fields)
+// 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`
 func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(4); err != nil {
 		return nil, err
@@ -233,6 +241,9 @@ func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, completerReturn), nil
 }
 
+// #interface completions
+// files(query, ctx, fields)
+// Returns file completion candidates based on the provided query.
 func luaFileComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	query, ctx, fds, err := getCompleteParams(t, c)
 	if err != nil {
@@ -249,6 +260,9 @@ func luaFileComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext(t.Runtime, rt.TableValue(luaComps), rt.StringValue(pfx)), nil
 }
 
+// #interface completions
+// bins(query, ctx, fields)
+// Returns binary/executale completion candidates based on the provided query.
 func luaBinaryComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	query, ctx, fds, err := getCompleteParams(t, c)
 	if err != nil {
diff --git a/docs/api/hilbish/hilbish.completions.md b/docs/api/hilbish/hilbish.completions.md
index ee95bd0..2f17d1d 100644
--- a/docs/api/hilbish/hilbish.completions.md
+++ b/docs/api/hilbish/hilbish.completions.md
@@ -7,3 +7,19 @@ layout: apidoc
 ## Introduction
 The completions interface deals with tab completions.
 
+## Functions
+### call(name, query, ctx, fields)
+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`
+
+### handler(line, pos)
+The handler function is the callback for tab completion in Hilbish.
+You can check the completions doc for more info.
+
+### bins(query, ctx, fields)
+Returns binary/executale completion candidates based on the provided query.
+
+### files(query, ctx, fields)
+Returns file completion candidates based on the provided query.
+
diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua
index 8fefd60..9d8180e 100644
--- a/emmyLuaDocs/hilbish.lua
+++ b/emmyLuaDocs/hilbish.lua
@@ -7,6 +7,15 @@ local hilbish = {}
 --- @param cmd string
 function hilbish.aliases.add(alias, cmd) end
 
+--- 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`
+function hilbish.completions.call(name, query, ctx, fields) end
+
+--- The handler function is the callback for tab completion in Hilbish.
+--- You can check the completions doc for more info.
+function hilbish.completions.handler(line, pos) end
+
 --- Sets an alias of `cmd` to `orig`
 --- @param cmd string
 --- @param orig string
@@ -113,6 +122,12 @@ function hilbish.timeout(cb, time) end
 --- @param binName string
 function hilbish.which(name) end
 
+--- Returns binary/executale completion candidates based on the provided query.
+function hilbish.completions.bins(query, ctx, fields) end
+
+--- Returns file completion candidates based on the provided query.
+function hilbish.completions.files(query, ctx, fields) end
+
 --- Stops a timer.
 function hilbish.timers:stop() end