From a2e23f13107c6e55be64f6c62c7ecb269d476f0f Mon Sep 17 00:00:00 2001
From: sammyette <torchedsammy@gmail.com>
Date: Wed, 2 Apr 2025 21:30:16 -0400
Subject: [PATCH] docs: attempt

---
 cmd/docgen/docgen.go                 |   8 +-
 docs/api/hilbish/_index.md           |  95 ---------------
 docs/api/hilbish/hilbish.messages.md | 135 ++++++++++++++++++++++
 docs/api/hilbish/hilbish.runner.md   | 166 ++++++++++++++++++++++-----
 docs/api/snail.md                    | 120 +++++++++++++++++++
 docs/nature/hilbish.md               |  53 +++++++++
 emmyLuaDocs/hilbish.lua              |  72 ++++--------
 emmyLuaDocs/snail.lua                |  26 +++++
 emmyLuaDocs/util.lua                 |  83 ++++++++++++++
 golibs/snail/lua.go                  |  19 ++-
 golibs/snail/snail.go                |  11 +-
 nature/snail.lua                     |   1 -
 12 files changed, 604 insertions(+), 185 deletions(-)
 create mode 100644 docs/api/hilbish/hilbish.messages.md
 create mode 100644 docs/api/snail.md
 create mode 100644 docs/nature/hilbish.md
 create mode 100644 emmyLuaDocs/snail.lua
 create mode 100644 emmyLuaDocs/util.lua

diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go
index 4743dea..eb42ce1 100644
--- a/cmd/docgen/docgen.go
+++ b/cmd/docgen/docgen.go
@@ -202,6 +202,7 @@ func setupDocType(mod string, typ *doc.Type) *docPiece {
 		Tags: tags,
 	}
 
+	fmt.Println(typeName, parentMod, interfaces)
 	typeTable[strings.ToLower(typeName)] = []string{parentMod, interfaces}
 
 	return dps
@@ -320,7 +321,7 @@ provided by Hilbish.
 
 	os.Mkdir("emmyLuaDocs", 0777)
 
-	dirs := []string{"./"}
+	dirs := []string{"./util", "./"}
 	filepath.Walk("golibs/", func (path string, info os.FileInfo, err error) error {
 		if !info.IsDir() {
 			return nil
@@ -347,7 +348,7 @@ provided by Hilbish.
 		pieces := []docPiece{}
 		typePieces := []docPiece{}
 		mod := l
-		if mod == "main" {
+		if mod == "main" || mod == "util" {
 			mod = "hilbish"
 		}
 		var hasInterfaces bool
@@ -471,9 +472,12 @@ provided by Hilbish.
 			f, _ := os.Create(docPath)
 			f.WriteString(fmt.Sprintf(header, modOrIface, modname, modu.ShortDescription))
 			typeTag, _ := regexp.Compile(`\B@\w+`)
+			//fmt.Println(modu.Description)
 			modDescription := typeTag.ReplaceAllStringFunc(strings.Replace(strings.Replace(modu.Description, "<", `\<`, -1), "{{\\<", "{{<", -1), func(typ string) string {
 				typName := typ[1:]
+				fmt.Println("typ name", typName)
 				typLookup := typeTable[strings.ToLower(typName)]
+				fmt.Println(typLookup)
 				ifaces := typLookup[0] + "." + typLookup[1] + "/"
 				if typLookup[1] == "" {
 					ifaces = ""
diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md
index 5c7a0f0..02ffea3 100644
--- a/docs/api/hilbish/_index.md
+++ b/docs/api/hilbish/_index.md
@@ -28,8 +28,6 @@ interfaces and functions which directly relate to shell functionality.
 |<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="#read">read(prompt) -> input (string)</a>|Read input from the user, using Hilbish's line editor/input reader.|
-|<a href="#run">run(cmd, streams) -> 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.|
 |<a href="#timeout">timeout(cb, time) -> @Timer</a>|Executed the `cb` function after a period of `time`.|
 |<a href="#which">which(name) -> string</a>|Checks if `name` is a valid command.|
 
@@ -408,72 +406,6 @@ Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs.
 `string` **`prompt?`**  
 Text to print before input, can be empty.
 
-</div>
-
-<hr>
-<div id='run'>
-<h4 class='heading'>
-hilbish.run(cmd, streams) -> exitCode (number), stdout (string), stderr (string)
-<a href="#run" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-Runs `cmd` in Hilbish's shell script interpreter.  
-The `streams` parameter specifies the output and input streams the command should use.  
-For example, to write command output to a sink.  
-As a table, the caller can directly specify the standard output, error, and input  
-streams of the command with the table keys `out`, `err`, and `input` respectively.  
-As a boolean, it specifies whether the command should use standard output or return its output streams.  
-
-#### Parameters
-`string` **`cmd`**  
-
-
-`table|boolean` **`streams`**  
-
-
-#### Example
-```lua
-
-// This code is the same as `ls -l | wc -l`
-local fs = require 'fs'
-local pr, pw = fs.pipe()
-hilbish.run('ls -l', {
-	stdout = pw,
-	stderr = pw,
-})
-
-pw:close()
-
-hilbish.run('wc -l', {
-	stdin = pr
-})
-
-```
-</div>
-
-<hr>
-<div id='runnerMode'>
-<h4 class='heading'>
-hilbish.runnerMode(mode)
-<a href="#runnerMode" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-Sets the execution/runner mode for interactive Hilbish.  
-This determines whether Hilbish wll try to run input as Lua  
-and/or sh or only do one of either.  
-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.  
-Read [about runner mode](../features/runner-mode) for more information.  
-
-#### Parameters
-`string|function` **`mode`**  
-
-
 </div>
 
 <hr>
@@ -515,30 +447,3 @@ Will return the path of the binary, or a basename if it's a commander.
 
 </div>
 
-## Types
-<hr>
-
-## Sink
-A sink is a structure that has input and/or output to/from
-a desination.
-
-### Methods
-#### autoFlush(auto)
-Sets/toggles the option of automatically flushing output.
-A call with no argument will toggle the value.
-
-#### flush()
-Flush writes all buffered input to the sink.
-
-#### read() -> string
-Reads a liine of input from the sink.
-
-#### readAll() -> string
-Reads all input from the sink.
-
-#### write(str)
-Writes data to a sink.
-
-#### writeln(str)
-Writes data to a sink with a newline at the end.
-
diff --git a/docs/api/hilbish/hilbish.messages.md b/docs/api/hilbish/hilbish.messages.md
new file mode 100644
index 0000000..2dff7a7
--- /dev/null
+++ b/docs/api/hilbish/hilbish.messages.md
@@ -0,0 +1,135 @@
+---
+title: Module hilbish.messages
+description: simplistic message passing
+layout: doc
+menu:
+  docs:
+    parent: "API"
+---
+
+
+## Introduction
+The messages interface defines a way for Hilbish-integrated commands,
+user config and other tasks to send notifications to alert the user.z
+The `hilbish.message` type is a table with the following keys:
+`title` (string): A title for the message notification.
+`text` (string): The contents of the message.
+`channel` (string): States the origin of the message, `hilbish.*` is reserved for Hilbish tasks.
+`summary` (string): A short summary of the `text`.
+`icon` (string): Unicode (preferably standard emoji) icon for the message notification
+`read` (boolean): Whether the full message has been read or not.
+
+## Functions
+|||
+|----|----|
+|<a href="#unreadCount">unreadCount()</a>|Returns the amount of unread messages.|
+|<a href="#readAll">readAll()</a>|Marks all messages as read.|
+|<a href="#send">send(message)</a>|Sends a message.|
+|<a href="#read">read(idx)</a>|Marks a message at `idx` as read.|
+|<a href="#delete">delete(idx)</a>|Deletes the message at `idx`.|
+|<a href="#clear">clear()</a>|Deletes all messages.|
+|<a href="#all">all()</a>|Returns all messages.|
+<hr>
+<div id='all'>
+<h4 class='heading'>
+hilbish.messages.all()
+<a href="#all" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Returns all messages.
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='clear'>
+<h4 class='heading'>
+hilbish.messages.clear()
+<a href="#clear" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Deletes all messages.
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='delete'>
+<h4 class='heading'>
+hilbish.messages.delete(idx)
+<a href="#delete" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Deletes the message at `idx`.
+#### Parameters
+`idx` **`number`**  
+
+
+</div>
+
+<hr>
+<div id='read'>
+<h4 class='heading'>
+hilbish.messages.read(idx)
+<a href="#read" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Marks a message at `idx` as read.
+#### Parameters
+`idx` **`number`**  
+
+
+</div>
+
+<hr>
+<div id='send'>
+<h4 class='heading'>
+hilbish.messages.send(message)
+<a href="#send" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Sends a message.
+#### Parameters
+`message` **`hilbish.message`**  
+
+
+</div>
+
+<hr>
+<div id='readAll'>
+<h4 class='heading'>
+hilbish.messages.readAll()
+<a href="#readAll" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Marks all messages as read.
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='unreadCount'>
+<h4 class='heading'>
+hilbish.messages.unreadCount()
+<a href="#unreadCount" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Returns the amount of unread messages.
+#### Parameters
+This function has no parameters.  
+</div>
+
diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md
index 8c89a52..7cb2522 100644
--- a/docs/api/hilbish/hilbish.runner.md
+++ b/docs/api/hilbish/hilbish.runner.md
@@ -54,29 +54,15 @@ end)
 ## Functions
 |||
 |----|----|
-|<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.|
-
-<hr>
-<div id='runner.setMode'>
-<h4 class='heading'>
-hilbish.runner.setMode(cb)
-<a href="#runner.setMode" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-This is the same as the `hilbish.runnerMode` function.  
-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
-`function` **`cb`**  
-
-
-</div>
+|<a href="#exec">exec(cmd, runnerName)</a>|Executes `cmd` with a runner.|
+|<a href="#set">set(name, runner)</a>|*Sets* a runner by name. The difference between this function and|
+|<a href="#get">get(name)</a>|Get a runner by name.|
+|<a href="#add">add(name, runner)</a>|Adds a runner to the table of available runners.|
+|<a href="#setCurrent">setCurrent(name)</a>|Sets Hilbish's runner mode by name.|
+|<a href="#getCurrent">getCurrent()</a>|Returns the current runner by name.|
+|<a href="#run">run(input, priv)</a>|Runs `input` with the currently set Hilbish runner.|
+|<a href="#sh">sh()</a>|nil|
 
 <hr>
 <div id='runner.lua'>
@@ -97,19 +83,143 @@ or `load`, but is appropriated for the runner interface.
 </div>
 
 <hr>
-<div id='runner.sh'>
+<div id='sh'>
 <h4 class='heading'>
-hilbish.runner.sh(cmd)
-<a href="#runner.sh" class='heading-link'>
+hilbish.runner.sh()
+<a href="#sh" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
 </h4>
 
-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>
+
+<hr>
+<div id='run'>
+<h4 class='heading'>
+hilbish.runner.run(input, priv)
+<a href="#run" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Runs `input` with the currently set Hilbish runner.
+This method is how Hilbish executes commands.
+`priv` is an optional boolean used to state if the input should be saved to history.
+#### Parameters
+`input` **`string`**  
+
+
+`priv` **`bool`**  
+
+
+</div>
+
+<hr>
+<div id='getCurrent'>
+<h4 class='heading'>
+hilbish.runner.getCurrent()
+<a href="#getCurrent" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Returns the current runner by name.
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='setCurrent'>
+<h4 class='heading'>
+hilbish.runner.setCurrent(name)
+<a href="#setCurrent" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Sets Hilbish's runner mode by name.
+#### Parameters
+`name` **`string`**  
+
+
+</div>
+
+<hr>
+<div id='add'>
+<h4 class='heading'>
+hilbish.runner.add(name, runner)
+<a href="#add" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Adds a runner to the table of available runners.
+If runner is a table, it must have the run function in it.
+#### Parameters
+`name` **`string`**  
+ Name of the runner
+
+`runner` **`function|table`**  
+ 
+
+</div>
+
+<hr>
+<div id='get'>
+<h4 class='heading'>
+hilbish.runner.get(name)
+<a href="#get" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Get a runner by name.
+#### Parameters
+`name` **`string`**  
+ Name of the runner to retrieve.
+
+</div>
+
+<hr>
+<div id='set'>
+<h4 class='heading'>
+hilbish.runner.set(name, runner)
+<a href="#set" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+*Sets* a runner by name. The difference between this function and
+add, is set will *not* check if the named runner exists.
+The runner table must have the run function in it.
+#### Parameters
+`name` **`string`**  
+
+
+`runner` **`table`**  
+
+
+</div>
+
+<hr>
+<div id='exec'>
+<h4 class='heading'>
+hilbish.runner.exec(cmd, runnerName)
+<a href="#exec" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Executes `cmd` with a runner.
+If `runnerName` is not specified, it uses the default Hilbish runner.
+#### Parameters
+`cmd` **`string`**  
+
+
+`runnerName` **`string?`**  
 
 
 </div>
diff --git a/docs/api/snail.md b/docs/api/snail.md
new file mode 100644
index 0000000..44847a9
--- /dev/null
+++ b/docs/api/snail.md
@@ -0,0 +1,120 @@
+---
+title: Module snail
+description: shell script interpreter library
+layout: doc
+menu:
+  docs:
+    parent: "API"
+---
+
+## Introduction
+
+	The snail library houses Hilbish's Lua wrapper of its shell script interpreter.
+	It's not very useful other than running shell scripts, which can be done with other
+	Hilbish functions.
+
+## Functions
+|||
+|----|----|
+|<a href="#handleStream"></a>||
+|<a href="#loaderFunc"></a>||
+|<a href="#snailUserData"></a>||
+|<a href="#snew">new() -> @Snail</a>|Creates a new Snail instance.|
+|<a href="#splitInput"></a>||
+|<a href="#Run"></a>||
+
+<hr>
+<div id='handleStream'>
+<h4 class='heading'>
+snail.
+<a href="#handleStream" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='loaderFunc'>
+<h4 class='heading'>
+snail.
+<a href="#loaderFunc" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='snailUserData'>
+<h4 class='heading'>
+snail.
+<a href="#snailUserData" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='snew'>
+<h4 class='heading'>
+snail.new() -> <a href="/Hilbish/docs/api/snail/#snail" style="text-decoration: none;" id="lol">Snail</a>
+<a href="#snew" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Creates a new Snail instance.  
+
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='splitInput'>
+<h4 class='heading'>
+snail.
+<a href="#splitInput" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='Run'>
+<h4 class='heading'>
+snail.
+<a href="#Run" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+
+#### Parameters
+This function has no parameters.  
+</div>
+
+## Types
+<hr>
+
+## Snail
+A Snail is a shell script interpreter instance.
+
+### Methods
+#### run(command, streams)
+Runs a shell command. Works the same as `hilbish.run`.
+
diff --git a/docs/nature/hilbish.md b/docs/nature/hilbish.md
new file mode 100644
index 0000000..830e241
--- /dev/null
+++ b/docs/nature/hilbish.md
@@ -0,0 +1,53 @@
+---
+title: Module hilbish
+description: No description.
+layout: doc
+menu:
+  docs:
+    parent: "Nature"
+---
+
+<hr>
+<div id='runner'>
+<h4 class='heading'>
+hilbish.runner(mode)
+<a href="#runner" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+**NOTE: This function is deprecated and will be removed in 3.0**
+Use `hilbish.runner.setCurrent` instead.
+This is the same as the `hilbish.runnerMode` function.
+It takes a callback, which will be used to execute all interactive input.
+Or a string which names the runner mode to use.
+#### Parameters
+`mode` **`string|function`**  
+
+
+</div>
+
+<hr>
+<div id='runnerMode'>
+<h4 class='heading'>
+hilbish.runnerMode(mode)
+<a href="#runnerMode" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+**NOTE: This function is deprecated and will be removed in 3.0**
+Use `hilbish.runner.setCurrent` instead.
+Sets the execution/runner mode for interactive Hilbish.
+This determines whether Hilbish wll try to run input as Lua
+and/or sh or only do one of either.
+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.
+Read [about runner mode](../features/runner-mode) for more information.
+#### Parameters
+`mode` **`string|function`**  
+
+
+</div>
+
diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua
index b80a660..e1ff9f2 100644
--- a/emmyLuaDocs/hilbish.lua
+++ b/emmyLuaDocs/hilbish.lua
@@ -2,17 +2,33 @@
 
 local hilbish = {}
 
+--- Sets/toggles the option of automatically flushing output.
+--- A call with no argument will toggle the value.
+--- @param auto boolean|nil
+function hilbish:autoFlush(auto) end
+
+--- Flush writes all buffered input to the sink.
+function hilbish:flush() end
+
+--- Reads a liine of input from the sink.
+--- @returns string
+function hilbish:read() end
+
+--- Reads all input from the sink.
+--- @returns string
+function hilbish:readAll() end
+
+--- Writes data to a sink.
+function hilbish:write(str) end
+
+--- Writes data to a sink with a newline at the end.
+function hilbish:writeln(str) end
+
 --- 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, 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.
-function hilbish.runner.setMode(cb) end
-
 --- Returns the current input line.
 function hilbish.editor.getLine() end
 
@@ -131,24 +147,6 @@ function hilbish.prompt(str, typ) end
 --- Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs.
 function hilbish.read(prompt) end
 
---- Runs `cmd` in Hilbish's shell script interpreter.
---- The `streams` parameter specifies the output and input streams the command should use.
---- For example, to write command output to a sink.
---- As a table, the caller can directly specify the standard output, error, and input
---- streams of the command with the table keys `out`, `err`, and `input` respectively.
---- As a boolean, it specifies whether the command should use standard output or return its output streams.
---- 
-function hilbish.run(cmd, streams) end
-
---- Sets the execution/runner mode for interactive Hilbish.
---- This determines whether Hilbish wll try to run input as Lua
---- and/or sh or only do one of either.
---- 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.
---- Read [about runner mode](../features/runner-mode) for more information.
-function hilbish.runnerMode(mode) end
-
 --- Executed the `cb` function after a period of `time`.
 --- This creates a Timer that starts ticking immediately.
 function hilbish.timeout(cb, time) end
@@ -168,28 +166,6 @@ function hilbish.jobs:foreground() end
 --- or `load`, but is appropriated for the runner interface.
 function hilbish.runner.lua(cmd) end
 
---- Sets/toggles the option of automatically flushing output.
---- A call with no argument will toggle the value.
---- @param auto boolean|nil
-function hilbish:autoFlush(auto) end
-
---- Flush writes all buffered input to the sink.
-function hilbish:flush() end
-
---- Reads a liine of input from the sink.
---- @returns string
-function hilbish:read() end
-
---- Reads all input from the sink.
---- @returns string
-function hilbish:readAll() end
-
---- Writes data to a sink.
-function hilbish:write(str) end
-
---- Writes data to a sink with a newline at the end.
-function hilbish:writeln(str) end
-
 --- Starts running the job.
 function hilbish.jobs:start() end
 
@@ -200,10 +176,6 @@ function hilbish.jobs:stop() end
 --- It will throw if any error occurs.
 function hilbish.module.load(path) end
 
---- Runs a command in Hilbish's shell script interpreter.
---- This is the equivalent of using `source`.
-function hilbish.runner.sh(cmd) end
-
 --- Starts a timer.
 function hilbish.timers:start() end
 
diff --git a/emmyLuaDocs/snail.lua b/emmyLuaDocs/snail.lua
new file mode 100644
index 0000000..f06a2e1
--- /dev/null
+++ b/emmyLuaDocs/snail.lua
@@ -0,0 +1,26 @@
+--- @meta
+
+local snail = {}
+
+--- 
+function snail. end
+
+--- 
+function snail. end
+
+--- 
+function snail. end
+
+--- Creates a new Snail instance.
+function snail.new() end
+
+--- 
+function snail. end
+
+--- Runs a shell command. Works the same as `hilbish.run`.
+function snail:run(command, streams) end
+
+--- 
+function snail. end
+
+return snail
diff --git a/emmyLuaDocs/util.lua b/emmyLuaDocs/util.lua
new file mode 100644
index 0000000..9f8d634
--- /dev/null
+++ b/emmyLuaDocs/util.lua
@@ -0,0 +1,83 @@
+--- @meta
+
+local util = {}
+
+--- 
+function util.AbbrevHome changes the user's home directory in the path string to ~ (tilde) end
+
+--- 
+function util. end
+
+--- 
+function util.DoFile runs the contents of the file in the Lua runtime. end
+
+--- 
+function util.DoString runs the code string in the Lua runtime. end
+
+--- directory.
+function util.ExpandHome expands ~ (tilde) in the path, changing it to the user home end
+
+--- 
+function util. end
+
+--- 
+function util.ForEach loops through a Lua table. end
+
+--- 
+function util. end
+
+--- a string and a closure.
+function util.HandleStrCallback handles function parameters for Go functions which take end
+
+--- 
+function util. end
+
+--- 
+function util. end
+
+--- 
+function util.SetExports puts the Lua function exports in the table. end
+
+--- It is accessible via the __docProp metatable. It is a table of the names of the fields.
+function util.SetField sets a field in a table, adding docs for it. end
+
+--- is one which has a metatable proxy to ensure no overrides happen to it.
+--- It sets the field in the table and sets the __docProp metatable on the
+--- user facing table.
+function util.SetFieldProtected sets a field in a protected table. A protected table end
+
+--- Sets/toggles the option of automatically flushing output.
+--- A call with no argument will toggle the value.
+--- @param auto boolean|nil
+function util:autoFlush(auto) end
+
+--- Flush writes all buffered input to the sink.
+function util:flush() end
+
+--- 
+function util. end
+
+--- Reads a liine of input from the sink.
+--- @returns string
+function util:read() end
+
+--- Reads all input from the sink.
+--- @returns string
+function util:readAll() end
+
+--- Writes data to a sink.
+function util:write(str) end
+
+--- Writes data to a sink with a newline at the end.
+function util:writeln(str) end
+
+--- 
+function util. end
+
+--- 
+function util. end
+
+--- 
+function util. end
+
+return util
diff --git a/golibs/snail/lua.go b/golibs/snail/lua.go
index 0095198..37357e5 100644
--- a/golibs/snail/lua.go
+++ b/golibs/snail/lua.go
@@ -1,3 +1,9 @@
+// shell script interpreter library
+/*
+	The snail library houses Hilbish's Lua wrapper of its shell script interpreter.
+	It's not very useful other than running shell scripts, which can be done with other
+	Hilbish functions.
+*/
 package snail
 
 import (
@@ -48,11 +54,16 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
 	return rt.TableValue(mod), nil
 }
 
+// new() -> @Snail
+// Creates a new Snail instance.
 func snew(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	s := New(t.Runtime)
 	return c.PushingNext1(t.Runtime, rt.UserDataValue(snailUserData(s))), nil
 }
 
+// #member
+// run(command, streams)
+// Runs a shell command. Works the same as `hilbish.run`.
 func srun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
 		return nil, err
@@ -157,7 +168,7 @@ func handleStream(v rt.Value, strms *util.Streams, errStream, inStream bool) err
 	return nil
 }
 
-func snailArg(c *rt.GoCont, arg int) (*snail, error) {
+func snailArg(c *rt.GoCont, arg int) (*Snail, error) {
 	s, ok := valueToSnail(c.Arg(arg))
 	if !ok {
 		return nil, fmt.Errorf("#%d must be a snail", arg + 1)
@@ -166,17 +177,17 @@ func snailArg(c *rt.GoCont, arg int) (*snail, error) {
 	return s, nil
 }
 
-func valueToSnail(val rt.Value) (*snail, bool) {
+func valueToSnail(val rt.Value) (*Snail, bool) {
 	u, ok := val.TryUserData()
 	if !ok {
 		return nil, false
 	}
 
-	s, ok := u.Value().(*snail)
+	s, ok := u.Value().(*Snail)
 	return s, ok
 }
 
-func snailUserData(s *snail) *rt.UserData {
+func snailUserData(s *Snail) *rt.UserData {
 	snailMeta := s.runtime.Registry(snailMetaKey)
 	return rt.NewUserData(s, snailMeta.AsTable())
 }
diff --git a/golibs/snail/snail.go b/golibs/snail/snail.go
index b09af3b..3ca1d12 100644
--- a/golibs/snail/snail.go
+++ b/golibs/snail/snail.go
@@ -1,4 +1,3 @@
-// shell script interpreter library
 package snail
 
 import (
@@ -23,21 +22,23 @@ import (
 	"mvdan.cc/sh/v3/expand"
 )
 
-type snail struct{
+// #type
+// A Snail is a shell script interpreter instance.
+type Snail struct{
 	runner *interp.Runner
 	runtime *rt.Runtime
 }
 
-func New(rtm *rt.Runtime) *snail {
+func New(rtm *rt.Runtime) *Snail {
 	runner, _ := interp.New()
 
-	return &snail{
+	return &Snail{
 		runner: runner,
 		runtime: rtm,
 	}
 }
 
-func (s *snail) Run(cmd string, strms *util.Streams) (bool, io.Writer, io.Writer, error){
+func (s *Snail) Run(cmd string, strms *util.Streams) (bool, io.Writer, io.Writer, error){
 	file, err := syntax.NewParser().Parse(strings.NewReader(cmd), "")
 	if err != nil {
 		return false, nil, nil, err
diff --git a/nature/snail.lua b/nature/snail.lua
index 2a9ce19..1ac1827 100644
--- a/nature/snail.lua
+++ b/nature/snail.lua
@@ -3,7 +3,6 @@ local snail = require 'snail'
 
 hilbish.snail = snail.new()
 
---- run(cmd, streams) -> exitCode (number), stdout (string), stderr (string)
 --- Runs `cmd` in Hilbish's shell script interpreter.
 --- The `streams` parameter specifies the output and input streams the command should use.
 --- For example, to write command output to a sink.