Merge 1f7f8e5104 into 29e14c1aee

aliases.go

@@ -111,23 +111,15 @@ func (a *aliasModule) Loader(rtm *rt.Runtime) *rt.Table {
 
 // #interface aliases
 // add(alias, cmd)
-// This is an alias (ha) for the [hilbish.alias](../#alias) function.
+// This is an alias (ha) for the `hilbish.alias` function.
 // --- @param alias string
 // --- @param cmd string
 func _hlalias() {}
 
 // #interface aliases
-// list() -> table[string, string]
+// list() -> table<string, string>
 // Get a table of all aliases, with string keys as the alias and the value as the command.
-// #returns table[string, string]
+// --- @returns table<string, string>
-/*
-#example
-hilbish.aliases.add('hi', 'echo hi')
-
-local aliases = hilbish.aliases.list()
--- -> {hi = 'echo hi'}
-#example
-*/
 func (a *aliasModule) luaList(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	aliasesList := rt.NewTable()
 	for k, v := range a.All() {
@@ -140,7 +132,7 @@ func (a *aliasModule) luaList(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // #interface aliases
 // delete(name)
 // Removes an alias.
-// #param name string
+// --- @param name string
 func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -155,10 +147,10 @@ func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface aliases
-// resolve(alias) -> string?
+// resolve(alias) -> command (string)
-// Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.
+// Tries to resolve an alias to its command.
-// #param alias string
+// --- @param alias string
-// #returns 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

@@ -140,9 +140,7 @@ func hilbishLoad(rtm *rt.Runtime) (rt.Value, func()) {
 
 	// hilbish.completion table
 	hshcomp := completionLoader(rtm)
-	// TODO: REMOVE "completion" AND ONLY USE "completions" WITH AN S
 	mod.Set(rt.StringValue("completion"), rt.TableValue(hshcomp))
-	mod.Set(rt.StringValue("completions"), rt.TableValue(hshcomp))
 
 	// hilbish.runner table
 	runnerModule := runnerModeLoader(rtm)
@@ -192,10 +190,12 @@ func unsetVimMode() {
 }
 
 // run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)
-// Runs `cmd` in Hilbish's shell script interpreter.
+// Runs `cmd` in Hilbish's sh interpreter.
-// #param cmd string
+// If returnOut is true, the outputs of `cmd` will be returned as the 2nd and
-// #param returnOut boolean If this is true, the function will return the standard output and error of the command instead of printing it.
+// 3rd values instead of being outputted to the terminal.
-// #returns number, string, string
+// --- @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,7 +238,7 @@ func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 // cwd() -> string
 // Returns the current directory of the shell
-// #returns string
+// --- @returns string
 func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	cwd, _ := os.Getwd()
 
@@ -249,9 +249,9 @@ func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // 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).
+// Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen)
-// #param prompt? string
+// --- @param prompt? string
-// #returns string|nil
+// --- @returns string|nil
 func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	luaprompt := c.Arg(0)
 	if typ := luaprompt.Type(); typ != rt.StringType && typ != rt.NilType {
@@ -279,21 +279,14 @@ func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 /*
 prompt(str, typ)
-Changes the shell prompt to the provided string.
+Changes the shell prompt to `str`
 There are a few verbs that can be used in the prompt text.
 These will be formatted and replaced with the appropriate values.
 `%d` - Current working directory
 `%u` - Name of current user
 `%h` - Hostname of device
-#param str string
+--- @param str string
-#param typ? string Type of prompt, being left or right. Left by default.
+--- @param typ? string Type of prompt, being left or right. Left by default.
-#example
--- the default hilbish prompt without color
-hilbish.prompt '%u %d ∆'
--- or something of old:
-hilbish.prompt '%u@%h :%d $'
--- prompt: user@hostname: ~/directory $
-#example
 */
 func hlprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	err := c.Check1Arg()
@@ -327,28 +320,8 @@ func hlprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // multiprompt(str)
-// Changes the text prompt when Hilbish asks for more input.
+// Changes the continued line prompt to `str`
-// This will show up when text is incomplete, like a missing quote
+// --- @param str string
-// #param str string
-/*
-#example
---[[
-imagine this is your text input:
-user ~ ∆ echo "hey
-
-but there's a missing quote! hilbish will now prompt you so the terminal
-will look like:
-user ~ ∆ echo "hey
---> ...!"
-
-so then you get 
-user ~ ∆ echo "hey
---> ...!"
-hey ...!
-]]--
-hilbish.multiprompt '-->'
-#example
-*/
 func hlmultiprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -442,9 +415,8 @@ func appendPath(dir string) {
 }
 
 // exec(cmd)
-// Replaces the currently running Hilbish instance with the supplied command.
+// Replaces running hilbish with `cmd`
-// This can be used to do an in-place restart.
+// --- @param cmd string
-// #param cmd string
 func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -478,10 +450,8 @@ func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // goro(fn)
-// Puts `fn` in a Goroutine.
+// Puts `fn` in a goroutine
-// This can be used to run any function in another thread.
+// --- @param fn function
-// **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**
-// #param fn function
 func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -504,10 +474,10 @@ func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 // timeout(cb, time) -> @Timer
 // Runs the `cb` function after `time` in milliseconds.
-// This creates a Timer that starts immediately.
+// This creates a timer that starts immediately.
-// #param cb function
+// --- @param cb function
-// #param time number
+// --- @param time number
-// #returns Timer
+// --- @returns Timer
 func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
 		return nil, err
@@ -531,9 +501,9 @@ func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // interval(cb, time) -> @Timer
 // Runs the `cb` function every `time` milliseconds.
 // This creates a timer that starts immediately.
-// #param cb function
+// --- @param cb function
-// #param time number
+// --- @param time number
-// #return Timer
+// --- @return Timer
 func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
 		return nil, err
@@ -555,13 +525,13 @@ func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // complete(scope, cb)
-// Registers a completion handler for the specified scope.
+// Registers a completion handler for `scope`.
 // A `scope` is currently only expected to be `command.<cmd>`,
 // replacing <cmd> with the name of the command (for example `command.git`).
-// The documentation for completions, under Features/Completions or `doc completions`
+// `cb` must be a function that returns a table of "completion groups."
-// provides more details.
+// Check `doc completions` for more information.
-// #param scope string
+// --- @param scope string
-// #param cb function
+// --- @param cb function
 func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	scope, cb, err := util.HandleStrCallback(t, c)
 	if err != nil {
@@ -573,8 +543,8 @@ func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // prependPath(dir)
-// Prepends `dir` to $PATH.
+// Prepends `dir` to $PATH
-// #param dir string
+// --- @param dir string
 func hlprependPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -597,8 +567,8 @@ func hlprependPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // which(name) -> string
 // Checks if `name` is a valid command.
 // Will return the path of the binary, or a basename if it's a commander.
-// #param name string
+// --- @param name string
-// #returns string
+// --- @returns string
 func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -628,10 +598,8 @@ func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // inputMode(mode)
-// Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.
+// Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
-// `emacs` is the default. Setting it to `vim` changes behavior of input to be
+// --- @param mode string
-// Vim-like with modes and Vim keybinds.
-// #param mode string
 func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -661,7 +629,7 @@ func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),
 // sh, and lua. It also accepts a function, to which if it is passed one
 // will call it to execute user input instead.
-// #param mode string|function
+// --- @param mode string|function
 func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -687,33 +655,26 @@ func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // line and cursor position. It is expected to return a string which is used
 // 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 line string
-// #param pos number
+// --- @param pos number
-/*
-#example
--- this will display "hi" after the cursor in a dimmed color.
-function hilbish.hinter(line, pos)
-	return 'hi'
-end
-#example
-*/
 func hlhinter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
 // highlighter(line)
-// Line highlighter handler.
+// Line highlighter handler. This is mainly for syntax highlighting, but in
-// This is mainly for syntax highlighting, but in reality could set the input
+// reality could set the input of the prompt to *display* anything. The
-// of the prompt to *display* anything. The callback is passed the current line
+// callback is passed the current line and is expected to return a line that
-// and is expected to return a line that will be used as the input display.
+// will be used as the input display.
 // Note that to set a highlighter, one has to override this function.
-// #example
+// Example:
-// --This code will highlight all double quoted strings in green.
+// ```
 // function hilbish.highlighter(line)
 //    return line:gsub('"%w+"', function(c) return lunacolors.green(c) end)
 // end
-// #example
+// ```
-// #param line string
+// This code will highlight all double quoted strings in green.
+// --- @param line string
 func hlhighlighter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }

complete.go

@@ -188,15 +188,15 @@ func escapeFilename(fname string) string {
 	return escapeReplaer.Replace(fname)
 }
 
-// #interface completion
+// #interface completions
 // tab completions
 // The completions interface deals with tab completions.
 func completionLoader(rtm *rt.Runtime) *rt.Table {
 	exports := map[string]util.LuaExport{
-		"bins": {hcmpBins, 3, false},
+		"files": {luaFileComplete, 3, false},
-		"call": {hcmpCall, 4, false},
+		"bins": {luaBinaryComplete, 3, false},
-		"files": {hcmpFiles, 3, false},
+		"call": {callLuaCompleter, 4, false},
-		"handler": {hcmpHandler, 2, false},
+		"handler": {completionHandler, 2, false},
 	}
 
 	mod := rt.NewTable()
@@ -205,58 +205,27 @@ func completionLoader(rtm *rt.Runtime) *rt.Table {
 	return mod
 }
 
-// #interface completion
+// #interface completions
-// bins(query, ctx, fields) -> entries (table), prefix (string)
+// handler(line, pos)
-// Return binaries/executables based on the provided parameters.
+// The handler function is the callback for tab completion in Hilbish.
-// This function is meant to be used as a helper in a command completion handler.
+// You can check the completions doc for more info.
-// #param query string
+// --- @param line string
-// #param ctx string
+// --- @param pos string
-// #param fields table
+func completionHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
-/*
+	return c.Next(), nil
-#example
--- an extremely simple completer for sudo.
-hilbish.complete('command.sudo', function(query, ctx, fields)
-	table.remove(fields, 1)
-	if #fields[1] then
-		-- return commands because sudo runs a command as root..!
-
-		local entries, pfx = hilbish.completion.bins(query, ctx, fields)
-		return {
-			type = 'grid',
-			items = entries
-		}, pfx
-	end
-
-	-- ... else suggest files or anything else ..
-end)
-#example
-*/
-func hcmpBins(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
-	query, ctx, fds, err := getCompleteParams(t, c)
-	if err != nil {
-		return nil, err
 }
 
-	completions, pfx := binaryComplete(query, ctx, fds)
+// #interface completions
-	luaComps := rt.NewTable()
-
-	for i, comp := range completions {
-		luaComps.Set(rt.IntValue(int64(i + 1)), rt.StringValue(comp))
-	}
-
-	return c.PushingNext(t.Runtime, rt.TableValue(luaComps), rt.StringValue(pfx)), nil
-}
-
-// #interface completion
 // 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`
+// Calls a completer function. This is mainly used to call
-// in the form of `command.name`, example: `command.git`.
+// a command completer, which will have a `name` in the form
-// You can check the Completions doc or `doc completions` for info on the `completionGroups` return value.
+// of `command.name`, example: `command.git`.
-// #param name string
+// You can check `doc completions` for info on the `completionGroups` return value.
-// #param query string
+// --- @param name string
-// #param ctx string
+// --- @param query string
-// #param fields table
+// --- @param ctx string
-func hcmpCall(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
+// --- @param fields table
+func callLuaCompleter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(4); err != nil {
 		return nil, err
 	}
@@ -296,14 +265,13 @@ func hcmpCall(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return cont, nil
 }
 
-// #interface completion
+// #interface completions
 // files(query, ctx, fields) -> entries (table), prefix (string)
-// Returns file matches based on the provided parameters.
+// Returns file completion candidates based on the provided query.
-// This function is meant to be used as a helper in a command completion handler.
+// --- @param query string
-// #param query string
+// --- @param ctx string
-// #param ctx string
+// --- @param fields table
-// #param fields table
+func luaFileComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
-func hcmpFiles(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	query, ctx, fds, err := getCompleteParams(t, c)
 	if err != nil {
 		return nil, err
@@ -319,31 +287,27 @@ func hcmpFiles(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext(t.Runtime, rt.TableValue(luaComps), rt.StringValue(pfx)), nil
 }
 
-// #interface completion
+// #interface completions
-// handler(line, pos)
+// bins(query, ctx, fields) -> entries (table), prefix (string)
-// This function contains the general completion handler for Hilbish. This function handles
+// Returns binary/executale completion candidates based on the provided query.
-// completion of everything, which includes calling other command handlers, binaries, and files.
+// --- @param query string
-// This function can be overriden to supply a custom handler. Note that alias resolution is required to be done in this function.
+// --- @param ctx string
-// #param line string The current Hilbish command line
+// --- @param fields table
-// #param pos number Numerical position of the cursor
+func luaBinaryComplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
-/*
+	query, ctx, fds, err := getCompleteParams(t, c)
-#example
+	if err != nil {
--- stripped down version of the default implementation
+		return nil, err
-function hilbish.completion.handler(line, pos)
-	local query = fields[#fields]
-
-	if #fields == 1 then
-		-- call bins handler here
-	else
-		-- call command completer or files completer here
-	end
-end
-#example
-*/
-func hcmpHandler(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
-	return c.Next(), nil
 	}
 
+	completions, pfx := binaryComplete(query, ctx, fds)
+	luaComps := rt.NewTable()
+
+	for i, comp := range completions {
+		luaComps.Set(rt.IntValue(int64(i + 1)), rt.StringValue(comp))
+	}
+
+	return c.PushingNext(t.Runtime, rt.TableValue(luaComps), rt.StringValue(pfx)), nil
+}
 
 func getCompleteParams(t *rt.Thread, c *rt.GoCont) (string, string, []string, error) {
 	if err := c.CheckNArgs(3); err != nil {

docs/api/hilbish/_index.md

@@ -16,19 +16,19 @@ interfaces and functions which directly relate to shell functionality.
 |----|----|
 |<a href="#alias">alias(cmd, orig)</a>|Sets an alias, with a name of `cmd` to another command.|
 |<a href="#appendPath">appendPath(dir)</a>|Appends the provided dir to the command path (`$PATH`)|
-|<a href="#complete">complete(scope, cb)</a>|Registers a completion handler for the specified scope.|
+|<a href="#complete">complete(scope, cb)</a>|Registers a completion handler for `scope`.|
 |<a href="#cwd">cwd() -> string</a>|Returns the current directory of the shell|
-|<a href="#exec">exec(cmd)</a>|Replaces the currently running Hilbish instance with the supplied command.|
+|<a href="#exec">exec(cmd)</a>|Replaces running hilbish with `cmd`|
-|<a href="#goro">goro(fn)</a>|Puts `fn` in a Goroutine.|
+|<a href="#goro">goro(fn)</a>|Puts `fn` in a goroutine|
-|<a href="#highlighter">highlighter(line)</a>|Line highlighter handler.|
+|<a href="#highlighter">highlighter(line)</a>|Line highlighter handler. This is mainly for syntax highlighting, but in|
 |<a href="#hinter">hinter(line, pos)</a>|The command line hint handler. It gets called on every key insert to|
-|<a href="#inputMode">inputMode(mode)</a>|Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.|
+|<a href="#inputMode">inputMode(mode)</a>|Sets the input mode for Hilbish's line reader. Accepts either emacs or vim|
 |<a href="#interval">interval(cb, time) -> @Timer</a>|Runs the `cb` function every `time` milliseconds.|
-|<a href="#multiprompt">multiprompt(str)</a>|Changes the text prompt when Hilbish asks for more input.|
+|<a href="#multiprompt">multiprompt(str)</a>|Changes the continued line prompt to `str`|
-|<a href="#prependPath">prependPath(dir)</a>|Prepends `dir` to $PATH.|
+|<a href="#prependPath">prependPath(dir)</a>|Prepends `dir` to $PATH|
-|<a href="#prompt">prompt(str, typ)</a>|Changes the shell prompt to the provided string.|
+|<a href="#prompt">prompt(str, typ)</a>|Changes the shell prompt to `str`|
 |<a href="#read">read(prompt) -> input (string)</a>|Read input from the user, using Hilbish's line editor/input reader.|
-|<a href="#run">run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)</a>|Runs `cmd` in Hilbish's shell script interpreter.|
+|<a href="#run">run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)</a>|Runs `cmd` in Hilbish's sh interpreter.|
 |<a href="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish. This determines whether|
 |<a href="#timeout">timeout(cb, time) -> @Timer</a>|Runs the `cb` function after `time` in milliseconds.|
 |<a href="#which">which(name) -> string</a>|Checks if `name` is a valid command.|
@@ -111,18 +111,13 @@ hilbish.complete(scope, cb)
 </a>
 </h4>
 
-Registers a completion handler for the specified scope.  
+Registers a completion handler for `scope`.  
 A `scope` is currently only expected to be `command.<cmd>`,  
 replacing <cmd> with the name of the command (for example `command.git`).  
-The documentation for completions, under Features/Completions or `doc completions`  
+`cb` must be a function that returns a table of "completion groups."  
-provides more details.  
+Check `doc completions` for more information.  
 #### Parameters
-`string` **`scope`**  
+This function has no parameters.  
-
-
-`function` **`cb`**  
-
-
 </div>
 
 <hr><div id='cwd'>
@@ -146,12 +141,9 @@ hilbish.exec(cmd)
 </a>
 </h4>
 
-Replaces the currently running Hilbish instance with the supplied command.  
+Replaces running hilbish with `cmd`  
-This can be used to do an in-place restart.  
 #### Parameters
-`string` **`cmd`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='goro'>
@@ -162,13 +154,9 @@ hilbish.goro(fn)
 </a>
 </h4>
 
-Puts `fn` in a Goroutine.  
+Puts `fn` in a goroutine  
-This can be used to run any function in another thread.  
-**NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**  
 #### Parameters
-`function` **`fn`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='highlighter'>
@@ -179,23 +167,20 @@ hilbish.highlighter(line)
 </a>
 </h4>
 
-Line highlighter handler.  
+Line highlighter handler. This is mainly for syntax highlighting, but in  
-This is mainly for syntax highlighting, but in reality could set the input  
+reality could set the input of the prompt to *display* anything. The  
-of the prompt to *display* anything. The callback is passed the current line  
+callback is passed the current line and is expected to return a line that  
-and is expected to return a line that will be used as the input display.  
+will be used as the input display.  
 Note that to set a highlighter, one has to override this function.  
-  
+Example:  
-#### Parameters
+```  
-`string` **`line`**  
-
-
-#### Example
-```lua
---This code will highlight all double quoted strings in green.
 function hilbish.highlighter(line)  
    return line:gsub('"%w+"', function(c) return lunacolors.green(c) end)  
 end  
-````
+```  
+This code will highlight all double quoted strings in green.  
+#### Parameters
+This function has no parameters.  
 </div>
 
 <hr><div id='hinter'>
@@ -211,22 +196,8 @@ determine what text to use as an inline hint. It is passed the current
 line and cursor position. It is expected to return a string which is used  
 as the text for the hint. This is by default a shim. To set hints,  
 override this function with your custom handler.  
-  
-  
 #### Parameters
-`string` **`line`**  
+This function has no parameters.  
-
-
-`number` **`pos`**  
-
-
-#### Example
-```lua
--- this will display "hi" after the cursor in a dimmed color.
-function hilbish.hinter(line, pos)
-	return 'hi'
-end
-````
 </div>
 
 <hr><div id='inputMode'>
@@ -237,13 +208,9 @@ hilbish.inputMode(mode)
 </a>
 </h4>
 
-Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.  
+Sets the input mode for Hilbish's line reader. Accepts either emacs or vim  
-`emacs` is the default. Setting it to `vim` changes behavior of input to be  
-Vim-like with modes and Vim keybinds.  
 #### Parameters
-`string` **`mode`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='interval'>
@@ -257,12 +224,7 @@ hilbish.interval(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/
 Runs the `cb` function every `time` milliseconds.  
 This creates a timer that starts immediately.  
 #### Parameters
-`function` **`cb`**  
+This function has no parameters.  
-
-
-`number` **`time`**  
-
-
 </div>
 
 <hr><div id='multiprompt'>
@@ -273,32 +235,9 @@ hilbish.multiprompt(str)
 </a>
 </h4>
 
-Changes the text prompt when Hilbish asks for more input.  
+Changes the continued line prompt to `str`  
-This will show up when text is incomplete, like a missing quote  
-  
-  
 #### Parameters
-`string` **`str`**  
+This function has no parameters.  
-
-
-#### Example
-```lua
---[[
-imagine this is your text input:
-user ~ ∆ echo "hey
-
-but there's a missing quote! hilbish will now prompt you so the terminal
-will look like:
-user ~ ∆ echo "hey
---> ...!"
-
-so then you get
-user ~ ∆ echo "hey
---> ...!"
-hey ...!
-]]--
-hilbish.multiprompt '-->'
-````
 </div>
 
 <hr><div id='prependPath'>
@@ -309,11 +248,9 @@ hilbish.prependPath(dir)
 </a>
 </h4>
 
-Prepends `dir` to $PATH.  
+Prepends `dir` to $PATH  
 #### Parameters
-`string` **`dir`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='prompt'>
@@ -324,28 +261,14 @@ hilbish.prompt(str, typ)
 </a>
 </h4>
 
-Changes the shell prompt to the provided string.  
+Changes the shell prompt to `str`  
 There are a few verbs that can be used in the prompt text.  
 These will be formatted and replaced with the appropriate values.  
 `%d` - Current working directory  
 `%u` - Name of current user  
 `%h` - Hostname of device  
-  
 #### Parameters
-`string` **`str`**  
+This function has no parameters.  
-
-
-`string` **`typ?`**  
-Type of prompt, being left or right. Left by default.
-
-#### Example
-```lua
--- the default hilbish prompt without color
-hilbish.prompt '%u %d ∆'
--- or something of old:
-hilbish.prompt '%u@%h :%d $'
--- prompt: user@hostname: ~/directory $
-````
 </div>
 
 <hr><div id='read'>
@@ -358,11 +281,9 @@ hilbish.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).  
+Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen)  
 #### Parameters
-`string` **`prompt?`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='run'>
@@ -373,14 +294,11 @@ hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (strin
 </a>
 </h4>
 
-Runs `cmd` in Hilbish's shell script interpreter.  
+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.  
 #### Parameters
-`string` **`cmd`**  
+This function has no parameters.  
-
-
-`boolean` **`returnOut`**  
-If this is true, the function will return the standard output and error of the command instead of printing it.
-
 </div>
 
 <hr><div id='runnerMode'>
@@ -397,9 +315,7 @@ Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua)
 sh, and lua. It also accepts a function, to which if it is passed one  
 will call it to execute user input instead.  
 #### Parameters
-`string|function` **`mode`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='timeout'>
@@ -411,14 +327,9 @@ hilbish.timeout(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#
 </h4>
 
 Runs the `cb` function after `time` in milliseconds.  
-This creates a Timer that starts immediately.  
+This creates a timer that starts immediately.  
 #### Parameters
-`function` **`cb`**  
+This function has no parameters.  
-
-
-`number` **`time`**  
-
-
 </div>
 
 <hr><div id='which'>
@@ -432,9 +343,7 @@ hilbish.which(name) -> string
 Checks if `name` is a valid command.  
 Will return the path of the binary, or a basename if it's a commander.  
 #### Parameters
-`string` **`name`**  
+This function has no parameters.  
-
-
 </div>
 
 ## Types

docs/api/hilbish/hilbish.aliases.md

@@ -13,10 +13,10 @@ The alias interface deals with all command aliases in Hilbish.
 ## Functions
 |||
 |----|----|
-|<a href="#aliases.add">add(alias, cmd)</a>|This is an alias (ha) for the [hilbish.alias](../#alias) function.|
+|<a href="#aliases.add">add(alias, cmd)</a>|This is an alias (ha) for the `hilbish.alias` function.|
 |<a href="#aliases.delete">delete(name)</a>|Removes an alias.|
-|<a href="#aliases.list">list() -> table[string, string]</a>|Get a table of all aliases, with string keys as the alias and the value as the command.|
+|<a href="#aliases.list">list() -> table<string, string></a>|Get a table of all aliases, with string keys as the alias and the value as the command.|
-|<a href="#aliases.resolve">resolve(alias) -> string?</a>|Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.|
+|<a href="#aliases.resolve">resolve(alias) -> command (string)</a>|Tries to resolve an alias to its command.|
 
 <hr><div id='aliases.add'>
 <h4 class='heading'>
@@ -26,7 +26,7 @@ hilbish.aliases.add(alias, cmd)
 </a>
 </h4>
 
-This is an alias (ha) for the [hilbish.alias](../#alias) function.  
+This is an alias (ha) for the `hilbish.alias` function.  
 #### Parameters
 This function has no parameters.  
 </div>
@@ -41,45 +41,32 @@ hilbish.aliases.delete(name)
 
 Removes an alias.  
 #### Parameters
-`string` **`name`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='aliases.list'>
 <h4 class='heading'>
-hilbish.aliases.list() -> table[string, string]
+hilbish.aliases.list() -> table\<string, string>
 <a href="#aliases.list" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
 </h4>
 
 Get a table of all aliases, with string keys as the alias and the value as the command.  
-  
-  
 #### Parameters
 This function has no parameters.  
-#### Example
-```lua
-hilbish.aliases.add('hi', 'echo hi')
-
-local aliases = hilbish.aliases.list()
--- -> {hi = 'echo hi'}
-````
 </div>
 
 <hr><div id='aliases.resolve'>
 <h4 class='heading'>
-hilbish.aliases.resolve(alias) -> string?
+hilbish.aliases.resolve(alias) -> command (string)
 <a href="#aliases.resolve" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
 </h4>
 
-Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.  
+Tries to resolve an alias to its command.  
 #### Parameters
-`string` **`alias`**  
+This function has no parameters.  
-
-
 </div>
 

docs/api/hilbish/hilbish.completion.md

@@ -1,145 +0,0 @@
----
-title: Module hilbish.completion
-description: tab completions
-layout: doc
-menu:
-  docs:
-    parent: "API"
----
-
-## Introduction
-The completions interface deals with tab completions.
-
-## Functions
-|||
-|----|----|
-|<a href="#completion.bins">bins(query, ctx, fields) -> entries (table), prefix (string)</a>|Return binaries/executables based on the provided parameters.|
-|<a href="#completion.call">call(name, query, ctx, fields) -> completionGroups (table), prefix (string)</a>|Calls a completer function. This is mainly used to call a command completer, which will have a `name`|
-|<a href="#completion.files">files(query, ctx, fields) -> entries (table), prefix (string)</a>|Returns file matches based on the provided parameters.|
-|<a href="#completion.handler">handler(line, pos)</a>|This function contains the general completion handler for Hilbish. This function handles|
-
-<hr><div id='completion.bins'>
-<h4 class='heading'>
-hilbish.completion.bins(query, ctx, fields) -> entries (table), prefix (string)
-<a href="#completion.bins" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-Return binaries/executables based on the provided parameters.  
-This function is meant to be used as a helper in a command completion handler.  
-  
-  
-#### Parameters
-`string` **`query`**  
-
-
-`string` **`ctx`**  
-
-
-`table` **`fields`**  
-
-
-#### Example
-```lua
--- an extremely simple completer for sudo.
-hilbish.complete('command.sudo', function(query, ctx, fields)
-	table.remove(fields, 1)
-	if #fields[1] then
-		-- return commands because sudo runs a command as root..!
-
-		local entries, pfx = hilbish.completion.bins(query, ctx, fields)
-		return {
-			type = 'grid',
-			items = entries
-		}, pfx
-	end
-
-	-- ... else suggest files or anything else ..
-end)
-````
-</div>
-
-<hr><div id='completion.call'>
-<h4 class='heading'>
-hilbish.completion.call(name, query, ctx, fields) -> completionGroups (table), prefix (string)
-<a href="#completion.call" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-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`.  
-You can check the Completions doc or `doc completions` for info on the `completionGroups` return value.  
-#### Parameters
-`string` **`name`**  
-
-
-`string` **`query`**  
-
-
-`string` **`ctx`**  
-
-
-`table` **`fields`**  
-
-
-</div>
-
-<hr><div id='completion.files'>
-<h4 class='heading'>
-hilbish.completion.files(query, ctx, fields) -> entries (table), prefix (string)
-<a href="#completion.files" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-Returns file matches based on the provided parameters.  
-This function is meant to be used as a helper in a command completion handler.  
-#### Parameters
-`string` **`query`**  
-
-
-`string` **`ctx`**  
-
-
-`table` **`fields`**  
-
-
-</div>
-
-<hr><div id='completion.handler'>
-<h4 class='heading'>
-hilbish.completion.handler(line, pos)
-<a href="#completion.handler" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-This function contains the general completion handler for Hilbish. This function handles  
-completion of everything, which includes calling other command handlers, binaries, and files.  
-This function can be overriden to supply a custom handler. Note that alias resolution is required to be done in this function.  
-  
-  
-#### Parameters
-`string` **`line`**  
-The current Hilbish command line
-
-`number` **`pos`**  
-Numerical position of the cursor
-
-#### Example
-```lua
--- stripped down version of the default implementation
-function hilbish.completion.handler(line, pos)
-	local query = fields[#fields]
-
-	if #fields == 1 then
-		-- call bins handler here
-	else
-		-- call command completer or files completer here
-	end
-end
-````
-</div>
-

docs/api/hilbish/hilbish.completions.md

@@ -0,0 +1,76 @@
+---
+title: Module hilbish.completions
+description: tab completions
+layout: doc
+menu:
+  docs:
+    parent: "API"
+---
+
+## Introduction
+The completions interface deals with tab completions.
+
+## Functions
+|||
+|----|----|
+|<a href="#completions.call">call(name, query, ctx, fields) -> completionGroups (table), prefix (string)</a>|Calls a completer function. This is mainly used to call|
+|<a href="#completions.handler">handler(line, pos)</a>|The handler function is the callback for tab completion in Hilbish.|
+|<a href="#completions.bins">bins(query, ctx, fields) -> entries (table), prefix (string)</a>|Returns binary/executale completion candidates based on the provided query.|
+|<a href="#completions.files">files(query, ctx, fields) -> entries (table), prefix (string)</a>|Returns file completion candidates based on the provided query.|
+
+<hr><div id='completions.call'>
+<h4 class='heading'>
+hilbish.completions.call(name, query, ctx, fields) -> completionGroups (table), prefix (string)
+<a href="#completions.call" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+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`.  
+You can check `doc completions` for info on the `completionGroups` return value.  
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr><div id='completions.handler'>
+<h4 class='heading'>
+hilbish.completions.handler(line, pos)
+<a href="#completions.handler" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+The handler function is the callback for tab completion in Hilbish.  
+You can check the completions doc for more info.  
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr><div id='completions.bins'>
+<h4 class='heading'>
+hilbish.completions.bins(query, ctx, fields) -> entries (table), prefix (string)
+<a href="#completions.bins" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Returns binary/executale completion candidates based on the provided query.  
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr><div id='completions.files'>
+<h4 class='heading'>
+hilbish.completions.files(query, ctx, fields) -> entries (table), prefix (string)
+<a href="#completions.files" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Returns file completion candidates based on the provided query.  
+#### Parameters
+This function has no parameters.  
+</div>
+

docs/api/hilbish/hilbish.editor.md

@@ -16,8 +16,8 @@ directly interact with the line editor in use.
 |----|----|
 |<a href="#editor.getLine">getLine() -> string</a>|Returns the current input line.|
 |<a href="#editor.getVimRegister">getVimRegister(register) -> string</a>|Returns the text that is at the register.|
-|<a href="#editor.insert">insert(text)</a>|Inserts text into the Hilbish command line.|
+|<a href="#editor.insert">insert(text)</a>|Inserts text into the line.|
-|<a href="#editor.getChar">getChar() -> string</a>|Reads a keystroke from the user. This is in a format of something like Ctrl-L.|
+|<a href="#editor.getChar">getChar() -> string</a>|Reads a keystroke from the user. This is in a format|
 |<a href="#editor.setVimRegister">setVimRegister(register, text)</a>|Sets the vim register at `register` to hold the passed text.|
 
 <hr><div id='editor.getLine'>
@@ -43,9 +43,7 @@ hilbish.editor.getVimRegister(register) -> string
 
 Returns the text that is at the register.  
 #### Parameters
-`string` **`register`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='editor.insert'>
@@ -56,11 +54,9 @@ hilbish.editor.insert(text)
 </a>
 </h4>
 
-Inserts text into the Hilbish command line.  
+Inserts text into the line.  
 #### Parameters
-`string` **`text`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='editor.getChar'>
@@ -71,7 +67,8 @@ hilbish.editor.getChar() -> string
 </a>
 </h4>
 
-Reads a keystroke from the user. This is in a format of something like Ctrl-L.  
+Reads a keystroke from the user. This is in a format  
+of something like Ctrl-L..  
 #### Parameters
 This function has no parameters.  
 </div>
@@ -86,8 +83,6 @@ hilbish.editor.setVimRegister(register, text)
 
 Sets the vim register at `register` to hold the passed text.  
 #### Parameters
-`string` **`text`**  
+This function has no parameters.  
-
-
 </div>
 

docs/api/hilbish/hilbish.history.md

@@ -16,9 +16,9 @@ method of saving history.
 |||
 |----|----|
 |<a href="#history.add">add(cmd)</a>|Adds a command to the history.|
-|<a href="#history.all">all() -> table</a>|Retrieves all history as a table.|
+|<a href="#history.all">all() -> table</a>|Retrieves all history.|
 |<a href="#history.clear">clear()</a>|Deletes all commands from the history.|
-|<a href="#history.get">get(index)</a>|Retrieves a command from the history based on the `index`.|
+|<a href="#history.get">get(idx)</a>|Retrieves a command from the history based on the `idx`.|
 |<a href="#history.size">size() -> number</a>|Returns the amount of commands in the history.|
 
 <hr><div id='history.add'>
@@ -31,9 +31,7 @@ hilbish.history.add(cmd)
 
 Adds a command to the history.  
 #### Parameters
-`string` **`cmd`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='history.all'>
@@ -44,7 +42,7 @@ hilbish.history.all() -> table
 </a>
 </h4>
 
-Retrieves all history as a table.  
+Retrieves all history.  
 #### Parameters
 This function has no parameters.  
 </div>
@@ -64,17 +62,15 @@ This function has no parameters.
 
 <hr><div id='history.get'>
 <h4 class='heading'>
-hilbish.history.get(index)
+hilbish.history.get(idx)
 <a href="#history.get" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
 </h4>
 
-Retrieves a command from the history based on the `index`.  
+Retrieves a command from the history based on the `idx`.  
 #### Parameters
-`number` **`index`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='history.size'>

docs/api/hilbish/hilbish.jobs.md

@@ -17,11 +17,11 @@ interactive usage or with the functions defined below for use in external runner
 ## Functions
 |||
 |----|----|
-|<a href="#jobs.add">add(cmdstr, args, execPath)</a>|Creates a new job. This function does not run the job. This function is intended to be|
+|<a href="#jobs.add">add(cmdstr, args, execPath)</a>|Adds a new job to the job table. Note that this does not immediately run it.|
-|<a href="#jobs.all">all() -> table[@Job]</a>|Returns a table of all job objects.|
+|<a href="#jobs.all">all() -> table<@Job></a>|Returns a table of all job objects.|
-|<a href="#jobs.disown">disown(id)</a>|Disowns a job. This simply deletes it from the list of jobs without stopping it.|
+|<a href="#jobs.disown">disown(id)</a>|Disowns a job. This deletes it from the job table.|
 |<a href="#jobs.get">get(id) -> @Job</a>|Get a job object via its ID.|
-|<a href="#jobs.last">last() -> @Job</a>|Returns the last added job to the table.|
+|<a href="#jobs.last">last() -> @Job</a>|Returns the last added job from the table.|
 
 <hr><div id='jobs.add'>
 <h4 class='heading'>
@@ -31,29 +31,14 @@ hilbish.jobs.add(cmdstr, args, execPath)
 </a>
 </h4>
 
-Creates a new job. This function does not run the job. This function is intended to be  
+Adds a new job to the job table. Note that this does not immediately run it.  
-used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.  
-  
-  
 #### Parameters
-`string` **`cmdstr`**  
+This function has no parameters.  
-String that a user would write for the job
-
-`table` **`args`**  
-Arguments for the commands. Has to include the name of the command.
-
-`string` **`execPath`**  
-Binary to use to run the command. Does not
-
-#### Example
-```lua
-hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go')
-````
 </div>
 
 <hr><div id='jobs.all'>
 <h4 class='heading'>
-hilbish.jobs.all() -> table[<a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>]
+hilbish.jobs.all() -> table\<<a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>>
 <a href="#jobs.all" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
@@ -72,11 +57,9 @@ hilbish.jobs.disown(id)
 </a>
 </h4>
 
-Disowns a job. This simply deletes it from the list of jobs without stopping it.  
+Disowns a job. This deletes it from the job table.  
 #### Parameters
-`number` **`id`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='jobs.get'>
@@ -100,7 +83,7 @@ hilbish.jobs.last() -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" sty
 </a>
 </h4>
 
-Returns the last added job to the table.  
+Returns the last added job from the table.  
 #### Parameters
 This function has no parameters.  
 </div>

docs/api/hilbish/hilbish.module.md

@@ -64,8 +64,6 @@ hilbish.module.load(path)
 Loads a module at the designated `path`.  
 It will throw if any error occurs.  
 #### Parameters
-`string` **`path`**  
+This function has no parameters.  
-
-
 </div>
 

docs/api/hilbish/hilbish.os.md

@@ -1,6 +1,6 @@
 ---
 title: Module hilbish.os
-description: operating system info
+description: OS Info
 layout: doc
 menu:
   docs:
@@ -8,8 +8,9 @@ menu:
 ---
 
 ## Introduction
-Provides simple text information properties about the current operating system.
+The `os` interface provides simple text information properties about
-This mainly includes the name and version.
+the current OS on the systen. This mainly includes the name and
+version.
 
 ## Static module fields
 |||

docs/api/hilbish/hilbish.runner.md

@@ -17,7 +17,7 @@ write command in Fennel.
 ## Functions
 |||
 |----|----|
-|<a href="#runner.setMode">setMode(cb)</a>|This is the same as the `hilbish.runnerMode` function.|
+|<a href="#runner.setMode">setMode(cb)</a>|This is the same as the `hilbish.runnerMode` function. It takes a callback,|
 |<a href="#runner.lua">lua(cmd)</a>|Evaluates `cmd` as Lua input. This is the same as using `dofile`|
 |<a href="#runner.sh">sh(cmd)</a>|Runs a command in Hilbish's shell script interpreter.|
 
@@ -29,14 +29,12 @@ hilbish.runner.setMode(cb)
 </a>
 </h4>
 
-This is the same as the `hilbish.runnerMode` function.  
+This is the same as the `hilbish.runnerMode` function. It takes a callback,  
-It takes a callback, which will be used to execute all interactive input.  
+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.  
 #### Parameters
-`function` **`cb`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='runner.lua'>
@@ -50,9 +48,7 @@ hilbish.runner.lua(cmd)
 Evaluates `cmd` as Lua input. This is the same as using `dofile`  
 or `load`, but is appropriated for the runner interface.  
 #### Parameters
-`string` **`cmd`**  
+This function has no parameters.  
-
-
 </div>
 
 <hr><div id='runner.sh'>
@@ -66,8 +62,6 @@ hilbish.runner.sh(cmd)
 Runs a command in Hilbish's shell script interpreter.  
 This is the equivalent of using `source`.  
 #### Parameters
-`string` **`cmd`**  
+This function has no parameters.  
-
-
 </div>
 

docs/api/hilbish/hilbish.timers.md

@@ -14,10 +14,14 @@ a few seconds, you don't have to rely on timing tricks, as Hilbish has a
 timer API to set intervals and timeouts.
 
 These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc
-accessible with `doc hilbish`, or `Module hilbish` on the Website).
+accessible with `doc hilbish`). But if you want slightly more control over
+them, there is the `hilbish.timers` interface. It allows you to get
+a timer via ID and control them.
+
+All functions documented with the `Timer` type refer to a Timer object.
 
 An example of usage:
-```lua
+```
 local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function()
 	print 'hello!'
 end)
@@ -29,7 +33,7 @@ print(t.running) // true
 ## Functions
 |||
 |----|----|
-|<a href="#timers.create">create(type, time, callback) -> @Timer</a>|Creates a timer that runs based on the specified `time`.|
+|<a href="#timers.create">create(type, time, callback) -> @Timer</a>|Creates a timer that runs based on the specified `time` in milliseconds.|
 |<a href="#timers.get">get(id) -> @Timer</a>|Retrieves a timer via its ID.|
 
 ## Static module fields
@@ -46,17 +50,10 @@ hilbish.timers.create(type, time, callback) -> <a href="/Hilbish/docs/api/hilbis
 </a>
 </h4>
 
-Creates a timer that runs based on the specified `time`.  
+Creates a timer that runs based on the specified `time` in milliseconds.  
+The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`  
 #### Parameters
-`number` **`type`**  
+This function has no parameters.  
-What kind of timer to create, can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
-
-`number` **`time`**  
-The amount of time the function should run in milliseconds.
-
-`function` **`callback`**  
-The function to run for the timer.
-
 </div>
 
 <hr><div id='timers.get'>
@@ -69,9 +66,7 @@ hilbish.timers.get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#tim
 
 Retrieves a timer via its ID.  
 #### Parameters
-`number` **`id`**  
+This function has no parameters.  
-
-
 </div>
 
 ## Types

docs/api/terminal.md

@@ -14,8 +14,8 @@ The terminal library is a simple and lower level library for certain terminal in
 |||
 |----|----|
 |<a href="#restoreState">restoreState()</a>|Restores the last saved state of the terminal|
-|<a href="#saveState">saveState()</a>|Saves the current state of the terminal.|
+|<a href="#saveState">saveState()</a>|Saves the current state of the terminal|
-|<a href="#setRaw">setRaw()</a>|Puts the terminal into raw mode.|
+|<a href="#setRaw">setRaw()</a>|Puts the terminal in raw mode|
 |<a href="#size">size()</a>|Gets the dimensions of the terminal. Returns a table with `width` and `height`|
 
 <hr><div id='restoreState'>
@@ -39,7 +39,7 @@ terminal.saveState()
 </a>
 </h4>
 
-Saves the current state of the terminal.  
+Saves the current state of the terminal  
 #### Parameters
 This function has no parameters.  
 </div>
@@ -52,7 +52,7 @@ terminal.setRaw()
 </a>
 </h4>
 
-Puts the terminal into raw mode.  
+Puts the terminal in raw mode  
 #### Parameters
 This function has no parameters.  
 </div>
@@ -66,7 +66,7 @@ terminal.size()
 </h4>
 
 Gets the dimensions of the terminal. Returns a table with `width` and `height`  
-NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal.  
+Note: this is not the size in relation to the dimensions of the display  
 #### Parameters
 This function has no parameters.  
 </div>

docs/runner-mode.md

@@ -1,15 +1,7 @@
-Hilbish allows you to change how interactive text can be interpreted.
+Hilbish is *unique,* when interactive it first attempts to run input as
-This is mainly due to the fact that the default method Hilbish uses
+Lua and then tries shell script. But if you're normal, you wouldn't
-is that it runs Lua first and then falls back to shell script.
+really be using Hilbish anyway but you'd also not want this
-
+(or maybe want Lua only in some cases.)
-In some cases, someone might want to switch to just shell script to avoid
-it while interactive but still have a Lua config, or go full Lua to use
-Hilbish as a REPL. This also allows users to add alternative languages like
-Fennel as the interactive script runner.
-
-Runner mode can also be used to handle specific kinds of input before
-evaluating like normal, which is how [Link.hsh](https://github.com/TorchedSammy/Link.hsh)
-handles links.
 
 The "runner mode" of Hilbish is customizable via `hilbish.runnerMode`,
 which determines how Hilbish will run user input. By default, this is
@@ -35,20 +27,12 @@ hilbish.runnerMode(function(input)
 end)
 
 The `hilbish.runner` interface is an alternative to using `hilbish.runnerMode`
-and also provides the shell script and Lua runner functions that Hilbish itself uses.
+and also provides the sh and Lua runner functions that Hilbish itself uses.
-
+A runner function is expected to return 3 values: the input, exit code, and an error.
-A runner function is expected to return a table with the following values:
+The input return is there incase you need to prompt for more input.
-- `exitCode` (number): Exit code of the command
+If you don't, just return the input passed to the runner function.
-- `input` (string): The text input of the user. This is used by Hilbish to append extra input, in case
+The exit code has to be a number, it will be 0 otherwise and the error can be
-more is requested.
+`nil` to indicate no error.
-- `err` (string): A string that represents an error from the runner.
-This should only be set when, for example, there is a syntax error.
-It can be set to a few special values for Hilbish to throw the right
-hooks and have a better looking message.
-	- `<command>: not-found` will throw a `command.not-found` hook
-	based on what `<command>` is.
-	- `<command>: not-executable` will throw a `command.not-executable` hook.
-- `continue` (boolean): Whether Hilbish should prompt the user for no input
 
 ## Functions
 These are the "low level" functions for the `hilbish.runner` interface.
@@ -57,6 +41,21 @@ These are the "low level" functions for the `hilbish.runner` interface.
 + sh(input) -> table > Runs `input` in Hilbish's sh interpreter
 + lua(input) -> table > Evals `input` as Lua code
 
+The table value that runners return can have at least 4 values:
++ input (string): The full input text.
++ exitCode (number): Exit code (usually from a command)
++ continue (boolean): Whether to prompt the user for more input
+(in the case of incomplete syntax)
++ err (string): A string that represents an error from the runner.
+This should only be set when, for example, there is a syntax error.
+It can be set to a few special values for Hilbish to throw the right
+hooks and have a better looking message.
+
++ `<command>: not-found` will throw a `command.not-found` hook
+based on what `<command>` is.
++ `<command>: not-executable` will throw a `command.not-executable` hook.
+
+The others here are defined in Lua and have EmmyLua documentation.
 These functions should be preferred over the previous ones.
 + setCurrent(mode) > The same as `setMode`, but works with runners managed
 via the functions below.

editor.go

@@ -27,8 +27,7 @@ func editorLoader(rtm *rt.Runtime) *rt.Table {
 
 // #interface editor
 // insert(text)
-// Inserts text into the Hilbish command line.
+// Inserts text into the line.
-// #param text string
 func editorInsert(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -47,8 +46,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.
-// #aram register string
+// --- @param register string
-// #param text string
+// --- @param text string
 func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -72,7 +71,7 @@ func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // #interface editor
 // getVimRegister(register) -> string
 // Returns the text that is at the register.
-// #param register string
+// --- @param register string
 func editorGetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -91,7 +90,6 @@ func editorGetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // #interface editor
 // getLine() -> string
 // Returns the current input line.
-// #returns string
 func editorGetLine(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	buf := lr.rl.GetLine()
 
@@ -100,7 +98,8 @@ func editorGetLine(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 // #interface editor
 // getChar() -> string
-// Reads a keystroke from the user. This is in a format of something like Ctrl-L.
+// Reads a keystroke from the user. This is in a format
+// of something like Ctrl-L..
 func editorReadChar(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	buf := lr.rl.ReadChar()
 

emmyLuaDocs/hilbish.lua

@@ -2,54 +2,53 @@
 
 local hilbish = {}
 
---- This is an alias (ha) for the [hilbish.alias](../#alias) function.
+--- This is an alias (ha) for the `hilbish.alias` function.
 --- @param alias string
 --- @param cmd string
 function hilbish.aliases.add(alias, cmd) end
 
---- This is the same as the `hilbish.runnerMode` function.
+--- This is the same as the `hilbish.runnerMode` function. It takes a callback,
---- It takes a callback, which will be used to execute all interactive input.
+--- 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
 function hilbish.runner.setMode(cb) 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`.
+--- You can check `doc completions` for info on the `completionGroups` return value.
+--- @param name string
+--- @param query string
+--- @param ctx string
+--- @param fields table
+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.
+--- @param line string
+--- @param pos string
+function hilbish.completions.handler(line, pos) end
+
 --- Returns the current input line.
 function hilbish.editor.getLine() end
 
 --- Returns the text that is at the register.
+--- @param register string
 function hilbish.editor.getVimRegister(register) end
 
---- Inserts text into the Hilbish command line.
+--- Inserts text into the line.
 function hilbish.editor.insert(text) end
 
---- Reads a keystroke from the user. This is in a format of something like Ctrl-L.
+--- Reads a keystroke from the user. This is in a format
+--- of something like Ctrl-L..
 function hilbish.editor.getChar() end
 
 --- Sets the vim register at `register` to hold the passed text.
+--- @param register string
+--- @param text string
 function hilbish.editor.setVimRegister(register, text) end
 
---- Return binaries/executables based on the provided parameters.
---- This function is meant to be used as a helper in a command completion handler.
---- 
---- 
-function hilbish.completion.bins(query, ctx, fields) 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`.
---- You can check the Completions doc or `doc completions` for info on the `completionGroups` return value.
-function hilbish.completion.call(name, query, ctx, fields) end
-
---- Returns file matches based on the provided parameters.
---- This function is meant to be used as a helper in a command completion handler.
-function hilbish.completion.files(query, ctx, fields) end
-
---- This function contains the general completion handler for Hilbish. This function handles
---- completion of everything, which includes calling other command handlers, binaries, and files.
---- This function can be overriden to supply a custom handler. Note that alias resolution is required to be done in this function.
---- 
---- 
-function hilbish.completion.handler(line, pos) end
-
 --- Sets an alias, with a name of `cmd` to another command.
 --- 
 --- 
@@ -60,31 +59,40 @@ function hilbish.alias(cmd, orig) end
 --- 
 function hilbish.appendPath(dir) end
 
---- Registers a completion handler for the specified scope.
+--- Registers a completion handler for `scope`.
 --- A `scope` is currently only expected to be `command.<cmd>`,
 --- replacing <cmd> with the name of the command (for example `command.git`).
---- The documentation for completions, under Features/Completions or `doc completions`
+--- `cb` must be a function that returns a table of "completion groups."
---- provides more details.
+--- Check `doc completions` for more information.
+--- @param scope string
+--- @param cb function
 function hilbish.complete(scope, cb) end
 
 --- Returns the current directory of the shell
+--- @returns string
 function hilbish.cwd() end
 
---- Replaces the currently running Hilbish instance with the supplied command.
+--- Replaces running hilbish with `cmd`
---- This can be used to do an in-place restart.
+--- @param cmd string
 function hilbish.exec(cmd) end
 
---- Puts `fn` in a Goroutine.
+--- Puts `fn` in a goroutine
---- This can be used to run any function in another thread.
+--- @param fn function
---- **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**
 function hilbish.goro(fn) end
 
---- Line highlighter handler.
+--- Line highlighter handler. This is mainly for syntax highlighting, but in
---- This is mainly for syntax highlighting, but in reality could set the input
+--- reality could set the input of the prompt to *display* anything. The
---- of the prompt to *display* anything. The callback is passed the current line
+--- callback is passed the current line and is expected to return a line that
---- and is expected to return a line that will be used as the input display.
+--- will be used as the input display.
 --- Note that to set a highlighter, one has to override this function.
---- 
+--- Example:
+--- ```
+--- function hilbish.highlighter(line)
+---    return line:gsub('"%w+"', function(c) return lunacolors.green(c) end)
+--- end
+--- ```
+--- This code will highlight all double quoted strings in green.
+--- @param line string
 function hilbish.highlighter(line) end
 
 --- The command line hint handler. It gets called on every key insert to
@@ -92,43 +100,52 @@ function hilbish.highlighter(line) end
 --- line and cursor position. It is expected to return a string which is used
 --- 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 number
 function hilbish.hinter(line, pos) end
 
---- Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.
+--- Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
---- `emacs` is the default. Setting it to `vim` changes behavior of input to be
+--- @param mode string
---- Vim-like with modes and Vim keybinds.
 function hilbish.inputMode(mode) end
 
 --- Runs the `cb` function every `time` milliseconds.
 --- This creates a timer that starts immediately.
+--- @param cb function
+--- @param time number
+--- @return Timer
 function hilbish.interval(cb, time) end
 
---- Changes the text prompt when Hilbish asks for more input.
+--- Changes the continued line prompt to `str`
---- This will show up when text is incomplete, like a missing quote
+--- @param str string
---- 
---- 
 function hilbish.multiprompt(str) end
 
---- Prepends `dir` to $PATH.
+--- Prepends `dir` to $PATH
+--- @param dir string
 function hilbish.prependPath(dir) end
 
---- Changes the shell prompt to the provided string.
+--- Changes the shell prompt to `str`
 --- There are a few verbs that can be used in the prompt text.
 --- These will be formatted and replaced with the appropriate values.
 --- `%d` - Current working directory
 --- `%u` - Name of current user
 --- `%h` - Hostname of device
---- 
+--- @param str string
+--- @param typ? string Type of prompt, being left or right. Left by default.
 function hilbish.prompt(str, typ) end
 
 --- 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).
+--- Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen)
+--- @param prompt? string
+--- @returns string|nil
 function hilbish.read(prompt) end
 
---- Runs `cmd` in Hilbish's shell script interpreter.
+--- 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
 function hilbish.run(cmd, returnOut) end
 
 --- Sets the execution/runner mode for interactive Hilbish. This determines whether
@@ -136,25 +153,44 @@ function hilbish.run(cmd, returnOut) end
 --- Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),
 --- sh, and lua. It also accepts a function, to which if it is passed one
 --- will call it to execute user input instead.
+--- @param mode string|function
 function hilbish.runnerMode(mode) end
 
 --- Runs the `cb` function after `time` in milliseconds.
---- This creates a Timer that starts immediately.
+--- This creates a timer that starts immediately.
+--- @param cb function
+--- @param time number
+--- @returns Timer
 function hilbish.timeout(cb, time) end
 
 --- Checks if `name` is a valid command.
 --- Will return the path of the binary, or a basename if it's a commander.
+--- @param name string
+--- @returns string
 function hilbish.which(name) end
 
 --- Puts a job in the background. This acts the same as initially running a job.
 function hilbish.jobs:background() end
 
+--- Returns binary/executale completion candidates based on the provided query.
+--- @param query string
+--- @param ctx string
+--- @param fields table
+function hilbish.completions.bins(query, ctx, fields) end
+
+--- Returns file completion candidates based on the provided query.
+--- @param query string
+--- @param ctx string
+--- @param fields table
+function hilbish.completions.files(query, ctx, fields) end
+
 --- Puts a job in the foreground. This will cause it to run like it was
 --- executed normally and wait for it to complete.
 function hilbish.jobs:foreground() end
 
 --- Evaluates `cmd` as Lua input. This is the same as using `dofile`
 --- or `load`, but is appropriated for the runner interface.
+--- @param cmd string
 function hilbish.runner.lua(cmd) end
 
 --- Sets/toggles the option of automatically flushing output.
@@ -191,6 +227,7 @@ function hilbish.module.load(path) end
 
 --- Runs a command in Hilbish's shell script interpreter.
 --- This is the equivalent of using `source`.
+--- @param cmd string
 function hilbish.runner.sh(cmd) end
 
 --- Starts a timer.
@@ -200,26 +237,30 @@ function hilbish.timers:start() end
 function hilbish.timers:stop() end
 
 --- Removes an alias.
+--- @param name string
 function hilbish.aliases.delete(name) end
 
 --- Get a table of all aliases, with string keys as the alias and the value as the command.
---- 
+--- @returns table<string, string>
---- 
 function hilbish.aliases.list() end
 
---- Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.
+--- Tries to resolve an alias to its command.
+--- @param alias string
+--- @returns string
 function hilbish.aliases.resolve(alias) end
 
---- Creates a new job. This function does not run the job. This function is intended to be
+--- Adds a new job to the job table. Note that this does not immediately run it.
---- used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.
+--- @param cmdstr string
---- 
+--- @param args table
---- 
+--- @param execPath string
 function hilbish.jobs.add(cmdstr, args, execPath) end
 
 --- Returns a table of all job objects.
+--- @returns table<Job>
 function hilbish.jobs.all() end
 
---- Disowns a job. This simply deletes it from the list of jobs without stopping it.
+--- Disowns a job. This deletes it from the job table.
+--- @param id number
 function hilbish.jobs.disown(id) end
 
 --- Get a job object via its ID.
@@ -227,28 +268,39 @@ function hilbish.jobs.disown(id) end
 --- @returns Job
 function hilbish.jobs.get(id) end
 
---- Returns the last added job to the table.
+--- Returns the last added job from the table.
+--- @returns Job
 function hilbish.jobs.last() end
 
 --- Adds a command to the history.
+--- @param cmd string
 function hilbish.history.add(cmd) end
 
---- Retrieves all history as a table.
+--- Retrieves all history.
+--- @returns table
 function hilbish.history.all() end
 
 --- Deletes all commands from the history.
 function hilbish.history.clear() end
 
---- Retrieves a command from the history based on the `index`.
+--- Retrieves a command from the history based on the `idx`.
-function hilbish.history.get(index) end
+--- @param idx number
+function hilbish.history.get(idx) end
 
 --- Returns the amount of commands in the history.
+--- @returns number
 function hilbish.history.size() end
 
---- Creates a timer that runs based on the specified `time`.
+--- Creates a timer that runs based on the specified `time` in milliseconds.
+--- The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
+--- @param type number
+--- @param time number
+--- @param callback function
 function hilbish.timers.create(type, time, callback) end
 
 --- Retrieves a timer via its ID.
+--- @param id number
+--- @returns Timer
 function hilbish.timers.get(id) end
 
 return hilbish

emmyLuaDocs/terminal.lua

@@ -5,14 +5,14 @@ local terminal = {}
 --- Restores the last saved state of the terminal
 function terminal.restoreState() end
 
---- Saves the current state of the terminal.
+--- Saves the current state of the terminal
 function terminal.saveState() end
 
---- Puts the terminal into raw mode.
+--- Puts the terminal in raw mode
 function terminal.setRaw() end
 
 --- Gets the dimensions of the terminal. Returns a table with `width` and `height`
---- NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal.
+--- Note: this is not the size in relation to the dimensions of the display
 function terminal.size() end
 
 return terminal

golibs/terminal/terminal.go

@@ -34,7 +34,7 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
 
 // size()
 // Gets the dimensions of the terminal. Returns a table with `width` and `height`
-// NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal.
+// Note: this is not the size in relation to the dimensions of the display
 func termsize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	w, h, err := term.GetSize(int(os.Stdin.Fd()))
 	if err != nil {
@@ -49,7 +49,7 @@ func termsize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // saveState()
-// Saves the current state of the terminal.
+// Saves the current state of the terminal
 func termsaveState(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	state, err := term.GetState(int(os.Stdin.Fd()))
 	if err != nil {
@@ -72,7 +72,7 @@ func termrestoreState(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // setRaw()
-// Puts the terminal into raw mode.
+// Puts the terminal in raw mode
 func termsetRaw(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	_, err := term.MakeRaw(int(os.Stdin.Fd()))
 	if err != nil {

job.go

@@ -414,16 +414,10 @@ func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 // #interface jobs
 // add(cmdstr, args, execPath)
-// Creates a new job. This function does not run the job. This function is intended to be
+// Adds a new job to the job table. Note that this does not immediately run it.
-// used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.
+// --- @param cmdstr string
-// #param cmdstr string String that a user would write for the job
+// --- @param args table
-// #param args table Arguments for the commands. Has to include the name of the command.
+// --- @param execPath string
-// #param execPath string Binary to use to run the command. Does not 
-/*
-#example
-hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go')
-#example
-*/
 func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(3); err != nil {
 		return nil, err
@@ -454,9 +448,9 @@ func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface jobs
-// all() -> table[@Job]
+// all() -> table<@Job>
 // Returns a table of all job objects.
-// #returns table[Job]
+// --- @returns table<Job>
 func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	j.mu.RLock()
 	defer j.mu.RUnlock()
@@ -471,8 +465,8 @@ func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 // #interface jobs
 // disown(id)
-// Disowns a job. This simply deletes it from the list of jobs without stopping it.
+// Disowns a job. This deletes it from the job table.
-// #param id number
+// --- @param id number
 func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -492,8 +486,8 @@ func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 // #interface jobs
 // last() -> @Job
-// Returns the last added job to the table.
+// Returns the last added job from the table.
-// #returns Job
+// --- @returns Job
 func (j *jobHandler) luaLastJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	j.mu.RLock()
 	defer j.mu.RUnlock()

module.go

@@ -61,7 +61,6 @@ func moduleLoader(rtm *rt.Runtime) *rt.Table {
 // load(path)
 // Loads a module at the designated `path`.
 // It will throw if any error occurs.
-// #param path string 
 func moduleLoad(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(1); err != nil {
 		return nil, err

os.go

@@ -8,9 +8,10 @@ import (
 )
 
 // #interface os
-// operating system info
+// OS Info
-// Provides simple text information properties about the current operating system.
+// The `os` interface provides simple text information properties about
-// This mainly includes the name and version.
+// the current OS on the systen. This mainly includes the name and
+// version.
 // #field family Family name of the current OS
 // #field name Pretty name of the current OS
 // #field version Version of the current OS

rl.go

@@ -267,7 +267,7 @@ func (lr *lineReader) Loader(rtm *rt.Runtime) *rt.Table {
 // #interface history
 // add(cmd)
 // Adds a command to the history.
-// #param cmd string
+// --- @param cmd string
 func (lr *lineReader) luaAddHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -284,15 +284,15 @@ func (lr *lineReader) luaAddHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error)
 // #interface history
 // size() -> number
 // Returns the amount of commands in the history.
-// #eturns number
+// --- @returns number
 func (lr *lineReader) luaSize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, rt.IntValue(int64(lr.fileHist.Len()))), nil
 }
 
 // #interface history
-// get(index)
+// get(idx)
-// Retrieves a command from the history based on the `index`.
+// Retrieves a command from the history based on the `idx`.
-// #param index number
+// --- @param idx number
 func (lr *lineReader) luaGetHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -309,8 +309,8 @@ func (lr *lineReader) luaGetHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error)
 
 // #interface history
 // all() -> table
-// Retrieves all history as a table.
+// Retrieves all history.
-// #returns table
+// --- @returns table
 func (lr *lineReader) luaAllHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	tbl := rt.NewTable()
 	size := lr.fileHist.Len()

runnermode.go

@@ -28,18 +28,18 @@ func runnerModeLoader(rtm *rt.Runtime) *rt.Table {
 
 // #interface runner
 // setMode(cb)
-// This is the same as the `hilbish.runnerMode` function.
+// This is the same as the `hilbish.runnerMode` function. It takes a callback,
-// It takes a callback, which will be used to execute all interactive input.
+// 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
+// --- @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
+// --- @param cmd string
 func shRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -67,7 +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
+// --- @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

@@ -63,10 +63,11 @@ func (th *timersModule) get(id int) *timer {
 
 // #interface timers
 // create(type, time, callback) -> @Timer
-// Creates a timer that runs based on the specified `time`.
+// Creates a timer that runs based on the specified `time` in milliseconds.
-// #param type number What kind of timer to create, can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
+// The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
-// #param time number The amount of time the function should run in milliseconds.
+// --- @param type number
-// #param callback function The function to run for the timer.
+// --- @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
@@ -92,8 +93,8 @@ func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // #interface timers
 // get(id) -> @Timer
 // Retrieves a timer via its ID.
-// #param id number
+// --- @param id number
-// #returns Timer
+// --- @returns Timer
 func (th *timersModule) luaGet(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -121,10 +122,15 @@ a few seconds, you don't have to rely on timing tricks, as Hilbish has a
 timer API to set intervals and timeouts.
 
 These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc
-accessible with `doc hilbish`, or `Module hilbish` on the Website).
+accessible with `doc hilbish`). But if you want slightly more control over
+them, there is the `hilbish.timers` interface. It allows you to get
+a timer via ID and control them.
+
+## Timer Object
+All functions documented with the `Timer` type refer to a Timer object.
 
 An example of usage:
-```lua
+```
 local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function()
 	print 'hello!'
 end)

website/config.toml

@@ -35,7 +35,6 @@ lineNumbersInTable = false
 noClasses = false
 codeFences = true
 guessSyntax = true
-tabWidth = 4
 
 [author]
 	[author.sammyette]