refactor: update documentation for everything

aliases.go

@@ -111,15 +111,23 @@ func (a *aliasModule) Loader(rtm *rt.Runtime) *rt.Table {
 
 // #interface aliases
 // add(alias, cmd)
-// This is an alias (ha) for the `hilbish.alias` function.
+// This is an alias (ha) for the [hilbish.alias](../#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() {
@@ -132,7 +140,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
@@ -147,10 +155,10 @@ func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface aliases
-// resolve(alias) -> command (string)
+// resolve(alias) -> string?
-// Tries to resolve an alias to its command.
+// Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.
-// --- @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

@@ -190,12 +190,10 @@ func unsetVimMode() {
 }
 
 // run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)
-// Runs `cmd` in Hilbish's sh interpreter.
+// Runs `cmd` in Hilbish's shell script interpreter.
-// If returnOut is true, the outputs of `cmd` will be returned as the 2nd and
+// #param cmd string
-// 3rd values instead of being outputted to the terminal.
+// #param returnOut boolean If this is true, the function will return the standard output and error of the command instead of printing it.
-// --- @param cmd string
+// #returns number, string, 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 +236,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 +247,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,14 +277,21 @@ func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 /*
 prompt(str, typ)
-Changes the shell prompt to `str`
+Changes the shell prompt to the provided string.
 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()
@@ -320,8 +325,28 @@ func hlprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // multiprompt(str)
-// Changes the continued line prompt to `str`
+// Changes the text prompt when Hilbish asks for more input.
-// --- @param str string
+// This will show up when text is incomplete, like a missing quote
+// #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
@@ -415,8 +440,9 @@ func appendPath(dir string) {
 }
 
 // exec(cmd)
-// Replaces running hilbish with `cmd`
+// Replaces the currently running Hilbish instance with the supplied command.
-// --- @param cmd string
+// This can be used to do an in-place restart.
+// #param cmd string
 func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -450,8 +476,10 @@ func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // goro(fn)
-// Puts `fn` in a goroutine
+// Puts `fn` in a Goroutine.
-// --- @param fn function
+// This can be used to run any function in another thread.
+// **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
@@ -474,10 +502,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
@@ -501,9 +529,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
@@ -525,13 +553,13 @@ func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // complete(scope, cb)
-// Registers a completion handler for `scope`.
+// Registers a completion handler for the specified scope.
 // A `scope` is currently only expected to be `command.<cmd>`,
 // replacing <cmd> with the name of the command (for example `command.git`).
-// `cb` must be a function that returns a table of "completion groups."
+// The documentation for completions, under Features/Completions or `doc completions`
-// Check `doc completions` for more information.
+// provides more details.
-// --- @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 {
@@ -543,8 +571,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
@@ -567,8 +595,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
@@ -598,8 +626,10 @@ 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.
-// --- @param mode string
+// `emacs` is the default. Setting it to `vim` changes behavior of input to be
+// 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
@@ -629,7 +659,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
@@ -655,26 +685,33 @@ 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. This is mainly for syntax highlighting, but in
+// Line highlighter handler.
-// reality could set the input of the prompt to *display* anything. The
+// This is mainly for syntax highlighting, but in reality could set the input
-// callback is passed the current line and is expected to return a line that
+// of the prompt to *display* anything. The callback is passed the current line
-// will be used as the input display.
+// and is expected to return a line that 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
-// This code will highlight all double quoted strings in green.
+// #param line string
-// --- @param line string
 func hlhighlighter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), 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 `scope`.|
+|<a href="#complete">complete(scope, cb)</a>|Registers a completion handler for the specified scope.|
 |<a href="#cwd">cwd() -> string</a>|Returns the current directory of the shell|
-|<a href="#exec">exec(cmd)</a>|Replaces running hilbish with `cmd`|
+|<a href="#exec">exec(cmd)</a>|Replaces the currently running Hilbish instance with the supplied command.|
-|<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. This is mainly for syntax highlighting, but in|
+|<a href="#highlighter">highlighter(line)</a>|Line highlighter handler.|
 |<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 continued line prompt to `str`|
+|<a href="#multiprompt">multiprompt(str)</a>|Changes the text prompt when Hilbish asks for more input.|
-|<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 `str`|
+|<a href="#prompt">prompt(str, typ)</a>|Changes the shell prompt to the provided string.|
 |<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 sh interpreter.|
+|<a href="#run">run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)</a>|Runs `cmd` in Hilbish's shell script 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,13 +111,18 @@ hilbish.complete(scope, cb)
 </a>
 </h4>
 
-Registers a completion handler for `scope`.  
+Registers a completion handler for the specified scope.  
 A `scope` is currently only expected to be `command.<cmd>`,  
 replacing <cmd> with the name of the command (for example `command.git`).  
-`cb` must be a function that returns a table of "completion groups."  
+The documentation for completions, under Features/Completions or `doc completions`  
-Check `doc completions` for more information.  
+provides more details.  
 #### Parameters
-This function has no parameters.  
+`string` **`scope`**  
+
+
+`function` **`cb`**  
+
+
 </div>
 
 <hr><div id='cwd'>
@@ -141,9 +146,12 @@ hilbish.exec(cmd)
 </a>
 </h4>
 
-Replaces running hilbish with `cmd`  
+Replaces the currently running Hilbish instance with the supplied command.  
+This can be used to do an in-place restart.  
 #### Parameters
-This function has no parameters.  
+`string` **`cmd`**  
+
+
 </div>
 
 <hr><div id='goro'>
@@ -154,9 +162,13 @@ 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
-This function has no parameters.  
+`function` **`fn`**  
+
+
 </div>
 
 <hr><div id='highlighter'>
@@ -167,20 +179,23 @@ hilbish.highlighter(line)
 </a>
 </h4>
 
-Line highlighter handler. This is mainly for syntax highlighting, but in  
+Line highlighter handler.  
-reality could set the input of the prompt to *display* anything. The  
+This is mainly for syntax highlighting, but in reality could set the input  
-callback is passed the current line and is expected to return a line that  
+of the prompt to *display* anything. The callback is passed the current line  
-will be used as the input display.  
+and is expected to return a line that 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.  
 #### Parameters
-This function has no 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
+````
 </div>
 
 <hr><div id='hinter'>
@@ -196,8 +211,22 @@ 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
-This function has no parameters.  
+`string` **`line`**  
+
+
+`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'>
@@ -208,9 +237,13 @@ 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
-This function has no parameters.  
+`string` **`mode`**  
+
+
 </div>
 
 <hr><div id='interval'>
@@ -224,7 +257,12 @@ 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
-This function has no parameters.  
+`function` **`cb`**  
+
+
+`number` **`time`**  
+
+
 </div>
 
 <hr><div id='multiprompt'>
@@ -235,9 +273,32 @@ hilbish.multiprompt(str)
 </a>
 </h4>
 
-Changes the continued line prompt to `str`  
+Changes the text prompt when Hilbish asks for more input.  
+This will show up when text is incomplete, like a missing quote  
+  
+  
 #### Parameters
-This function has no parameters.  
+`string` **`str`**  
+
+
+#### 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'>
@@ -248,9 +309,11 @@ hilbish.prependPath(dir)
 </a>
 </h4>
 
-Prepends `dir` to $PATH  
+Prepends `dir` to $PATH.  
 #### Parameters
-This function has no parameters.  
+`string` **`dir`**  
+
+
 </div>
 
 <hr><div id='prompt'>
@@ -261,14 +324,28 @@ hilbish.prompt(str, typ)
 </a>
 </h4>
 
-Changes the shell prompt to `str`  
+Changes the shell prompt to the provided string.  
 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
-This function has no parameters.  
+`string` **`str`**  
+
+
+`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'>
@@ -281,9 +358,11 @@ 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
-This function has no parameters.  
+`string` **`prompt?`**  
+
+
 </div>
 
 <hr><div id='run'>
@@ -294,11 +373,14 @@ hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (strin
 </a>
 </h4>
 
-Runs `cmd` in Hilbish's sh interpreter.  
+Runs `cmd` in Hilbish's shell script 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
-This function has no parameters.  
+`string` **`cmd`**  
+
+
+`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'>
@@ -315,7 +397,9 @@ 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
-This function has no parameters.  
+`string|function` **`mode`**  
+
+
 </div>
 
 <hr><div id='timeout'>
@@ -327,9 +411,14 @@ 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
-This function has no parameters.  
+`function` **`cb`**  
+
+
+`number` **`time`**  
+
+
 </div>
 
 <hr><div id='which'>
@@ -343,7 +432,9 @@ 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
-This function has no parameters.  
+`string` **`name`**  
+
+
 </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` function.|
+|<a href="#aliases.add">add(alias, cmd)</a>|This is an alias (ha) for the [hilbish.alias](../#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) -> command (string)</a>|Tries to resolve an alias to its 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.|
 
 <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` function.  
+This is an alias (ha) for the [hilbish.alias](../#alias) function.  
 #### Parameters
 This function has no parameters.  
 </div>
@@ -41,32 +41,45 @@ hilbish.aliases.delete(name)
 
 Removes an alias.  
 #### Parameters
-This function has no parameters.  
+`string` **`name`**  
+
+
 </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) -> command (string)
+hilbish.aliases.resolve(alias) -> string?
 <a href="#aliases.resolve" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
 </h4>
 
-Tries to resolve an alias to its command.  
+Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.  
 #### Parameters
-This function has no parameters.  
+`string` **`alias`**  
+
+
 </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 line.|
+|<a href="#editor.insert">insert(text)</a>|Inserts text into the Hilbish command line.|
-|<a href="#editor.getChar">getChar() -> string</a>|Reads a keystroke from the user. This is in a format|
+|<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.setVimRegister">setVimRegister(register, text)</a>|Sets the vim register at `register` to hold the passed text.|
 
 <hr><div id='editor.getLine'>
@@ -43,7 +43,9 @@ hilbish.editor.getVimRegister(register) -> string
 
 Returns the text that is at the register.  
 #### Parameters
-This function has no parameters.  
+`string` **`register`**  
+
+
 </div>
 
 <hr><div id='editor.insert'>
@@ -54,9 +56,11 @@ hilbish.editor.insert(text)
 </a>
 </h4>
 
-Inserts text into the line.  
+Inserts text into the Hilbish command line.  
 #### Parameters
-This function has no parameters.  
+`string` **`text`**  
+
+
 </div>
 
 <hr><div id='editor.getChar'>
@@ -67,8 +71,7 @@ hilbish.editor.getChar() -> string
 </a>
 </h4>
 
-Reads a keystroke from the user. This is in a format  
+Reads a keystroke from the user. This is in a format of something like Ctrl-L.  
-of something like Ctrl-L..  
 #### Parameters
 This function has no parameters.  
 </div>
@@ -83,6 +86,8 @@ hilbish.editor.setVimRegister(register, text)
 
 Sets the vim register at `register` to hold the passed text.  
 #### Parameters
-This function has no parameters.  
+`string` **`text`**  
+
+
 </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.|
+|<a href="#history.all">all() -> table</a>|Retrieves all history as a table.|
 |<a href="#history.clear">clear()</a>|Deletes all commands from the history.|
-|<a href="#history.get">get(idx)</a>|Retrieves a command from the history based on the `idx`.|
+|<a href="#history.get">get(index)</a>|Retrieves a command from the history based on the `index`.|
 |<a href="#history.size">size() -> number</a>|Returns the amount of commands in the history.|
 
 <hr><div id='history.add'>
@@ -31,7 +31,9 @@ hilbish.history.add(cmd)
 
 Adds a command to the history.  
 #### Parameters
-This function has no parameters.  
+`string` **`cmd`**  
+
+
 </div>
 
 <hr><div id='history.all'>
@@ -42,7 +44,7 @@ hilbish.history.all() -> table
 </a>
 </h4>
 
-Retrieves all history.  
+Retrieves all history as a table.  
 #### Parameters
 This function has no parameters.  
 </div>
@@ -62,15 +64,17 @@ This function has no parameters.
 
 <hr><div id='history.get'>
 <h4 class='heading'>
-hilbish.history.get(idx)
+hilbish.history.get(index)
 <a href="#history.get" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
 </h4>
 
-Retrieves a command from the history based on the `idx`.  
+Retrieves a command from the history based on the `index`.  
 #### Parameters
-This function has no parameters.  
+`number` **`index`**  
+
+
 </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>|Adds a new job to the job table. Note that this does not immediately run it.|
+|<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.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 deletes it from the job table.|
+|<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.get">get(id) -> @Job</a>|Get a job object via its ID.|
-|<a href="#jobs.last">last() -> @Job</a>|Returns the last added job from the table.|
+|<a href="#jobs.last">last() -> @Job</a>|Returns the last added job to the table.|
 
 <hr><div id='jobs.add'>
 <h4 class='heading'>
@@ -31,14 +31,29 @@ hilbish.jobs.add(cmdstr, args, execPath)
 </a>
 </h4>
 
-Adds a new job to the job table. Note that this does not immediately run it.  
+Creates a new job. This function does not run the job. This function is intended to be  
+used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.  
+  
+  
 #### Parameters
-This function has no parameters.  
+`string` **`cmdstr`**  
+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>
@@ -57,9 +72,11 @@ hilbish.jobs.disown(id)
 </a>
 </h4>
 
-Disowns a job. This deletes it from the job table.  
+Disowns a job. This simply deletes it from the list of jobs without stopping it.  
 #### Parameters
-This function has no parameters.  
+`number` **`id`**  
+
+
 </div>
 
 <hr><div id='jobs.get'>
@@ -83,7 +100,7 @@ hilbish.jobs.last() -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" sty
 </a>
 </h4>
 
-Returns the last added job from the table.  
+Returns the last added job to the table.  
 #### Parameters
 This function has no parameters.  
 </div>

docs/api/hilbish/hilbish.module.md

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

docs/api/hilbish/hilbish.os.md

@@ -1,6 +1,6 @@
 ---
 title: Module hilbish.os
-description: OS Info
+description: operating system info
 layout: doc
 menu:
   docs:
@@ -8,9 +8,8 @@ menu:
 ---
 
 ## Introduction
-The `os` interface provides simple text information properties about
+Provides simple text information properties about the current operating system.
-the current OS on the systen. This mainly includes the name and
+This mainly includes the name and version.
-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. It takes a callback,|
+|<a href="#runner.setMode">setMode(cb)</a>|This is the same as the `hilbish.runnerMode` function.|
 |<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,12 +29,14 @@ hilbish.runner.setMode(cb)
 </a>
 </h4>
 
-This is the same as the `hilbish.runnerMode` function. It takes a callback,  
+This is the same as the `hilbish.runnerMode` function.  
-which will be used to execute all interactive input.  
+It takes a callback, 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
-This function has no parameters.  
+`function` **`cb`**  
+
+
 </div>
 
 <hr><div id='runner.lua'>
@@ -48,7 +50,9 @@ 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
-This function has no parameters.  
+`string` **`cmd`**  
+
+
 </div>
 
 <hr><div id='runner.sh'>
@@ -62,6 +66,8 @@ hilbish.runner.sh(cmd)
 Runs a command in Hilbish's shell script interpreter.  
 This is the equivalent of using `source`.  
 #### Parameters
-This function has no parameters.  
+`string` **`cmd`**  
+
+
 </div>
 

docs/api/hilbish/hilbish.timers.md

@@ -14,14 +14,10 @@ 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`). But if you want slightly more control over
+accessible with `doc hilbish`, or `Module hilbish` on the Website).
-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)
@@ -33,7 +29,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` in milliseconds.|
+|<a href="#timers.create">create(type, time, callback) -> @Timer</a>|Creates a timer that runs based on the specified `time`.|
 |<a href="#timers.get">get(id) -> @Timer</a>|Retrieves a timer via its ID.|
 
 ## Static module fields
@@ -50,10 +46,17 @@ hilbish.timers.create(type, time, callback) -> <a href="/Hilbish/docs/api/hilbis
 </a>
 </h4>
 
-Creates a timer that runs based on the specified `time` in milliseconds.  
+Creates a timer that runs based on the specified `time`.  
-The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`  
 #### Parameters
-This function has no parameters.  
+`number` **`type`**  
+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'>
@@ -66,7 +69,9 @@ hilbish.timers.get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#tim
 
 Retrieves a timer via its ID.  
 #### Parameters
-This function has no parameters.  
+`number` **`id`**  
+
+
 </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 in raw mode|
+|<a href="#setRaw">setRaw()</a>|Puts the terminal into 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 in raw mode  
+Puts the terminal into 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: this is not the size in relation to the dimensions of the display  
+NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal.  
 #### Parameters
 This function has no parameters.  
 </div>

docs/runner-mode.md

@@ -1,7 +1,15 @@
-Hilbish is *unique,* when interactive it first attempts to run input as
+Hilbish allows you to change how interactive text can be interpreted.
-Lua and then tries shell script. But if you're normal, you wouldn't
+This is mainly due to the fact that the default method Hilbish uses
-really be using Hilbish anyway but you'd also not want this
+is that it runs Lua first and then falls back to shell script.
-(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
@@ -27,12 +35,20 @@ hilbish.runnerMode(function(input)
 end)
 
 The `hilbish.runner` interface is an alternative to using `hilbish.runnerMode`
-and also provides the sh and Lua runner functions that Hilbish itself uses.
+and also provides the shell script and Lua runner functions that Hilbish itself uses.
-A runner function is expected to return 3 values: the input, exit code, and an error.
+
-The input return is there incase you need to prompt for more input.
+A runner function is expected to return a table with the following values:
-If you don't, just return the input passed to the runner function.
+- `exitCode` (number): Exit code of the command
-The exit code has to be a number, it will be 0 otherwise and the error can be
+- `input` (string): The text input of the user. This is used by Hilbish to append extra input, in case
-`nil` to indicate no error.
+more is requested.
+- `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.
@@ -41,21 +57,6 @@ 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,7 +27,8 @@ func editorLoader(rtm *rt.Runtime) *rt.Table {
 
 // #interface editor
 // insert(text)
-// Inserts text into the line.
+// Inserts text into the Hilbish command line.
+// #param text string
 func editorInsert(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -46,8 +47,8 @@ func editorInsert(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // #interface editor
 // setVimRegister(register, text)
 // Sets the vim register at `register` to hold the passed text.
-// --- @param register string
+// #aram 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
@@ -71,7 +72,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
@@ -90,6 +91,7 @@ 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()
 
@@ -98,8 +100,7 @@ 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
+// Reads a keystroke from the user. This is in a format of something like Ctrl-L.
-// of something like Ctrl-L..
 func editorReadChar(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	buf := lr.rl.ReadChar()
 

emmyLuaDocs/hilbish.lua

@@ -2,35 +2,30 @@
 
 local hilbish = {}
 
---- This is an alias (ha) for the `hilbish.alias` function.
+--- This is an alias (ha) for the [hilbish.alias](../#alias) function.
 --- @param alias string
 --- @param cmd string
 function hilbish.aliases.add(alias, cmd) end
 
---- This is the same as the `hilbish.runnerMode` function. It takes a callback,
+--- This is the same as the `hilbish.runnerMode` function.
---- which will be used to execute all interactive input.
+--- It takes a callback, 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
 
 --- 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 line.
+--- Inserts text into the Hilbish command line.
 function hilbish.editor.insert(text) end
 
---- Reads a keystroke from the user. This is in a format
+--- Reads a keystroke from the user. This is in a format of something like Ctrl-L.
---- 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.
@@ -65,40 +60,31 @@ function hilbish.alias(cmd, orig) end
 --- 
 function hilbish.appendPath(dir) end
 
---- Registers a completion handler for `scope`.
+--- Registers a completion handler for the specified scope.
 --- A `scope` is currently only expected to be `command.<cmd>`,
 --- replacing <cmd> with the name of the command (for example `command.git`).
---- `cb` must be a function that returns a table of "completion groups."
+--- The documentation for completions, under Features/Completions or `doc completions`
---- Check `doc completions` for more information.
+--- provides more details.
---- @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 running hilbish with `cmd`
+--- Replaces the currently running Hilbish instance with the supplied command.
---- @param cmd string
+--- This can be used to do an in-place restart.
 function hilbish.exec(cmd) end
 
---- Puts `fn` in a goroutine
+--- Puts `fn` in a Goroutine.
---- @param fn function
+--- This can be used to run any function in another thread.
+--- **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**
 function hilbish.goro(fn) end
 
---- Line highlighter handler. This is mainly for syntax highlighting, but in
+--- Line highlighter handler.
---- reality could set the input of the prompt to *display* anything. The
+--- This is mainly for syntax highlighting, but in reality could set the input
---- callback is passed the current line and is expected to return a line that
+--- of the prompt to *display* anything. The callback is passed the current line
---- will be used as the input display.
+--- and is expected to return a line that 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
@@ -106,52 +92,43 @@ 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.
---- @param mode string
+--- `emacs` is the default. Setting it to `vim` changes behavior of input to be
+--- 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 continued line prompt to `str`
+--- Changes the text prompt when Hilbish asks for more input.
---- @param str string
+--- This will show up when text is incomplete, like a missing quote
+--- 
+--- 
 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 `str`
+--- Changes the shell prompt to the provided string.
 --- 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 sh interpreter.
+--- Runs `cmd` in Hilbish's shell script 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
@@ -159,20 +136,14 @@ 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.
@@ -184,7 +155,6 @@ 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.
@@ -221,7 +191,6 @@ 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.
@@ -231,30 +200,26 @@ 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
 
---- Tries to resolve an alias to its command.
+--- Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.
---- @param alias string
---- @returns string
 function hilbish.aliases.resolve(alias) end
 
---- Adds a new job to the job table. Note that this does not immediately run it.
+--- Creates a new job. This function does not run the job. This function is intended to be
---- @param cmdstr string
+--- used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.
---- @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 deletes it from the job table.
+--- Disowns a job. This simply deletes it from the list of jobs without stopping it.
---- @param id number
 function hilbish.jobs.disown(id) end
 
 --- Get a job object via its ID.
@@ -262,39 +227,28 @@ function hilbish.jobs.disown(id) end
 --- @returns Job
 function hilbish.jobs.get(id) end
 
---- Returns the last added job from the table.
+--- Returns the last added job to 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.
+--- Retrieves all history as a table.
---- @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 `idx`.
+--- Retrieves a command from the history based on the `index`.
---- @param idx number
+function hilbish.history.get(index) end
-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` in milliseconds.
+--- Creates a timer that runs based on the specified `time`.
---- 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 in raw mode
+--- Puts the terminal into raw mode.
 function terminal.setRaw() end
 
 --- Gets the dimensions of the terminal. Returns a table with `width` and `height`
---- Note: this is not the size in relation to the dimensions of the display
+--- NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal.
 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: this is not the size in relation to the dimensions of the display
+// NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal.
 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 in raw mode
+// Puts the terminal into 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,10 +414,16 @@ func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 // #interface jobs
 // add(cmdstr, args, execPath)
-// Adds a new job to the job table. Note that this does not immediately run it.
+// Creates a new job. This function does not run the job. This function is intended to be
-// --- @param cmdstr string
+// used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.
-// --- @param args table
+// #param cmdstr string String that a user would write for the job
-// --- @param execPath string
+// #param args table Arguments for the commands. Has to include the name of the command.
+// #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
@@ -448,9 +454,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()
@@ -465,8 +471,8 @@ func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 // #interface jobs
 // disown(id)
-// Disowns a job. This deletes it from the job table.
+// Disowns a job. This simply deletes it from the list of jobs without stopping it.
-// --- @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
@@ -486,8 +492,8 @@ func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 // #interface jobs
 // last() -> @Job
-// Returns the last added job from the table.
+// Returns the last added job to 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,6 +61,7 @@ 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,10 +8,9 @@ import (
 )
 
 // #interface os
-// OS Info
+// operating system info
-// The `os` interface provides simple text information properties about
+// Provides simple text information properties about the current operating system.
-// the current OS on the systen. This mainly includes the name and
+// This mainly includes the name and version.
-// 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.
-// --- @returns number
+// #eturns 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(idx)
+// get(index)
-// Retrieves a command from the history based on the `idx`.
+// Retrieves a command from the history based on the `index`.
-// --- @param idx number
+// #param index 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.
+// Retrieves all history as a table.
-// --- @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. It takes a callback,
+// This is the same as the `hilbish.runnerMode` function.
-// which will be used to execute all interactive input.
+// It takes a callback, 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,11 +63,10 @@ func (th *timersModule) get(id int) *timer {
 
 // #interface timers
 // create(type, time, callback) -> @Timer
-// Creates a timer that runs based on the specified `time` in milliseconds.
+// Creates a timer that runs based on the specified `time`.
-// The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
+// #param type number What kind of timer to create, can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
-// --- @param type number
+// #param time number The amount of time the function should run in milliseconds.
-// --- @param time number
+// #param callback function The function to run for the timer.
-// --- @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
@@ -93,8 +92,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
@@ -122,15 +121,10 @@ 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`). But if you want slightly more control over
+accessible with `doc hilbish`, or `Module hilbish` on the Website).
-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,6 +35,7 @@ lineNumbersInTable = false
 noClasses = false
 codeFences = true
 guessSyntax = true
+tabWidth = 4
 
 [author]
 	[author.sammyette]