fix: make lua implemented hilbish interfaces documented (#335)

* fix: make lua implemented hilbish interfaces documented

* fix: signature link in table of contents

* fix: reduce function list to match in go generated docs

* fix: toc appending

* docs: enable docs for hilbish.messages

* feat: add description gen, and more spacing between param listing

* docs: add more detailed documentation for lua modules

* docs: update hilbish.messages docs

* fix: add description for lua doc'd modules, remove duplicate docs

* docs: add back hilbish.jobs doc

* feat: generate toc for lua modules

* fix: add table heading

* ci: add lua docgen

* docs: put dirs.old doc on 1 line

.github/workflows/docs.yml

@@ -11,8 +11,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
-      - name: Run docgen
+      - name: Download Task
+        run: 'sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d'
+      - name: Build
+        run: ./bin/task
+      - name: Run docgen (go-written)
         run: go run cmd/docgen/docgen.go
+      - name: Run docgen (lua-written)
+        run: ./hilbish cmd/docgen/docgen.lua
       - name: Commit new docs
         uses: stefanzweifel/git-auto-commit-action@v4
         with:

cmd/docgen/docgen.go

@@ -299,7 +299,25 @@ start:
 func main() {
 	fset := token.NewFileSet()
 	os.Mkdir("docs", 0777)
+	os.RemoveAll("docs/api")
 	os.Mkdir("docs/api", 0777)
+
+	f, err := os.Create("docs/api/_index.md")
+	if err != nil {
+		panic(err)
+	}
+	f.WriteString(`---
+title: API
+layout: doc
+weight: -100
+menu: docs
+---
+
+Welcome to the API documentation for Hilbish. This documents Lua functions
+provided by Hilbish.
+`)
+	f.Close()
+
 	os.Mkdir("emmyLuaDocs", 0777)
 
 	dirs := []string{"./"}

cmd/docgen/docgen.lua

@@ -1,7 +1,9 @@
 local fs = require 'fs'
 local emmyPattern = '^%-%-%- (.+)'
-local modpattern = '^%-+ @module (%w+)'
+local emmyPattern2 = '^%-%- (.+)'
+local modpattern = '^%-+ @module (.+)'
 local pieces = {}
+local descriptions = {}
 
 local files = fs.readdir 'nature'
 for _, fname in ipairs(files) do
@@ -15,16 +17,24 @@ for _, fname in ipairs(files) do
 
 	print(fname, mod)
 	pieces[mod] = {}
+	descriptions[mod] = {}
 
 	local docPiece = {}
 	local lines = {}
 	local lineno = 0
+	local doingDescription = true
+
 	for line in f:lines() do
 		lineno = lineno + 1
 		lines[lineno] = line
 
 		if line == header then goto continue2 end
-		if not line:match(emmyPattern) then
+		if line:match(emmyPattern) or line:match(emmyPattern2) then
+			if doingDescription then
+				table.insert(descriptions[mod], line:match(emmyPattern) or line:match(emmyPattern2))
+			end
+		else
+			doingDescription = false
 			if line:match '^function' then
 				local pattern = (string.format('^function %s%%.', mod) .. '(%w+)')
 				local funcName = line:match(pattern)
@@ -49,10 +59,14 @@ for _, fname in ipairs(files) do
 
 						if emmy then
 							if emmy == 'param' then
+								print('bruh', emmythings[1], emmythings[2])
 								table.insert(dps.params, 1, {
 									name = emmythings[1],
-									type = emmythings[2]
+									type = emmythings[2],
+									-- the +1 accounts for space.
+									description = table.concat(emmythings, ' '):sub(emmythings[1]:len() + 1 + emmythings[2]:len() + 1)
 								})
+								print(table.concat(emmythings, '/'))
 							end
 						else
 							table.insert(dps.description, 1, docline)
@@ -81,30 +95,79 @@ description: %s
 layout: doc
 menu:
   docs:
-    parent: "Nature"
+    parent: "%s"
 ---
 
 ]]
 
 for iface, dps in pairs(pieces) do
 	local mod = iface:match '(%w+)%.' or 'nature'
-	local path = string.format('docs/%s/%s.md', mod, iface)
+	local docParent = 'Nature'
+
+	path = string.format('docs/%s/%s.md', mod, iface)
+	if mod ~= 'nature' then
+		docParent = "API"
+		path = string.format('docs/api/%s/%s.md', mod, iface)
+	end
+
 	fs.mkdir(fs.dir(path), true)
-	local f <close> = io.open(path, 'w')
+
-	f:write(string.format(header, 'Module', iface, 'No description.'))
+	local exists = pcall(fs.stat, path)
+	local newOrNotNature = exists and mod ~= 'nature'
+
+	local f <close> = io.open(path, newOrNotNature and 'r+' or 'w+')
+	local tocPos
+	if not newOrNotNature then
+		f:write(string.format(header, 'Module', iface, (descriptions[iface] and #descriptions[iface] > 0) and descriptions[iface][1] or 'No description.', docParent))
+		if descriptions[iface] and #descriptions[iface] > 0 then
+			table.remove(descriptions[iface], 1)
+			f:write(string.format('\n## Introduction\n%s\n\n', table.concat(descriptions[iface], '\n')))
+			f:write('## Functions\n')
+			f:write([[|||
+|----|----|
+]])
+			tocPos = f:seek()
+		end
+	end
 	print(f)
 
-	print(mod, path)
+	print('mod and path:', mod, path)
+
+	local tocSearch = false
+	for line in f:lines() do
+		if line:match '^## Functions' then
+			tocSearch = true
+		end
+		if tocSearch and line == '' then
+			tocSearch = false
+			tocPos = f:seek() - 1
+		end
+	end
 
 	for func, docs in pairs(dps) do
-		f:write(string.format('<hr>\n<div id=\'%s\'>', func))
 		local sig = string.format('%s.%s(', iface, func)
+		local params = ''
 		for idx, param in ipairs(docs.params) do
-			sig = sig .. ((param.name:gsub('%?$', '')))
+			sig = sig .. param.name:gsub('%?$', '')
-			if idx ~= #docs.params then sig = sig .. ', ' end
+			params = params .. param.name:gsub('%?$', '')
+			if idx ~= #docs.params then
+				sig = sig .. ', '
+				params = params .. ', '
+			end
 		end
 		sig = sig .. ')'
-		f:write(string.format([[			
+
+		if tocPos then
+			f:seek('set', tocPos)
+			local contents = f:read '*a'
+			f:seek('set', tocPos)
+			local tocLine = string.format('|<a href="#%s">%s</a>|%s|\n', func, string.format('%s(%s)', func, params), docs.description[1])
+			f:write(tocLine .. contents)
+			f:seek 'end'
+		end
+
+		f:write(string.format('<hr>\n<div id=\'%s\'>\n', func))
+		f:write(string.format([[
 <h4 class='heading'>
 %s
 <a href="#%s" class='heading-link'>
@@ -120,7 +183,8 @@ for iface, dps in pairs(pieces) do
 			f:write 'This function has no parameters.  \n'
 		end
 		for _, param in ipairs(docs.params) do
-			f:write(string.format('`%s` **`%s`**\n', param.name:gsub('%?$', ''), param.type))
+			f:write(string.format('`%s` **`%s`**  \n', param.name:gsub('%?$', ''), param.type))
+			f:write(string.format('%s\n\n', param.description))
 		end
 		--[[
 		local params = table.filter(docs, function(t)

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>
+

docs/api/hilbish/hilbish.runner.md

@@ -57,6 +57,12 @@ end)
 |<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.|
+|<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.|
 
 <hr>
 <div id='runner.setMode'>
@@ -114,3 +120,110 @@ This is the equivalent of using `source`.
 
 </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>
+

docs/nature/dirs.md

@@ -1,14 +1,27 @@
 ---
 title: Module dirs
-description: No description.
+description: internal directory management
 layout: doc
 menu:
   docs:
     parent: "Nature"
 ---
 
+
+## Introduction
+The dirs module defines a small set of functions to store and manage
+directories.
+
+## Functions
+|||
+|----|----|
+|<a href="#recent">recent(idx)</a>|Get entry from recent directories list based on index.|
+|<a href="#pop">pop(num)</a>|Remove the specified amount of dirs from the recent directories list.|
+|<a href="#peak">peak(num)</a>|Look at `num` amount of recent directories, starting from the latest.|
+|<a href="#push">push(dir)</a>|Add `dir` to the recent directories list.|
+|<a href="#setOld">setOld(d)</a>|Sets the old directory string.|
 <hr>
-<div id='setOld'>			
+<div id='setOld'>
 <h4 class='heading'>
 dirs.setOld(d)
 <a href="#setOld" class='heading-link'>
@@ -18,25 +31,29 @@ dirs.setOld(d)
 
 Sets the old directory string.
 #### Parameters
-`d` **`string`**
+`d` **`string`**  
+
+
 </div>
 
 <hr>
-<div id='push'>			
+<div id='push'>
 <h4 class='heading'>
-dirs.push()
+dirs.push(dir)
 <a href="#push" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
 </h4>
 
-Add `d` to the recent directories list.
+Add `dir` to the recent directories list.
 #### Parameters
-This function has no parameters.  
+`dir` **`string`**  
+
+
 </div>
 
 <hr>
-<div id='peak'>			
+<div id='peak'>
 <h4 class='heading'>
 dirs.peak(num)
 <a href="#peak" class='heading-link'>
@@ -45,12 +62,15 @@ dirs.peak(num)
 </h4>
 
 Look at `num` amount of recent directories, starting from the latest.
+This returns  a table of recent directories, up to the `num` amount.
 #### Parameters
-`num` **`number`**
+`num` **`number`**  
+
+
 </div>
 
 <hr>
-<div id='pop'>			
+<div id='pop'>
 <h4 class='heading'>
 dirs.pop(num)
 <a href="#pop" class='heading-link'>
@@ -60,11 +80,13 @@ dirs.pop(num)
 
 Remove the specified amount of dirs from the recent directories list.
 #### Parameters
-`num` **`number`**
+`num` **`number`**  
+
+
 </div>
 
 <hr>
-<div id='recent'>			
+<div id='recent'>
 <h4 class='heading'>
 dirs.recent(idx)
 <a href="#recent" class='heading-link'>
@@ -74,6 +96,8 @@ dirs.recent(idx)
 
 Get entry from recent directories list based on index.
 #### Parameters
-`idx` **`number`**
+`idx` **`number`**  
+
+
 </div>
 

docs/nature/doc.md

@@ -0,0 +1,76 @@
+---
+title: Module doc
+description: command-line doc rendering
+layout: doc
+menu:
+  docs:
+    parent: "Nature"
+---
+
+
+## Introduction
+The doc module contains a small set of functions
+used by the Greenhouse pager to render parts of the documentation pages.
+This is only documented for the sake of it. It's only intended use
+is by the Greenhouse pager.
+
+## Functions
+|||
+|----|----|
+|<a href="#renderCodeBlock">renderCodeBlock(text)</a>|Assembles and renders a code block. This returns|
+|<a href="#highlight">highlight(text)</a>|Performs basic Lua code highlighting.|
+|<a href="#renderInfoBlock">renderInfoBlock(type, text)</a>|Renders an info block. An info block is a block of text with|
+<hr>
+<div id='renderInfoBlock'>
+<h4 class='heading'>
+doc.renderInfoBlock(type, text)
+<a href="#renderInfoBlock" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Renders an info block. An info block is a block of text with
+an icon and styled text block.
+#### Parameters
+`type` **`string`**  
+ Type of info block. The only one specially styled is the `warning`.
+
+`text` **`string`**  
+
+
+</div>
+
+<hr>
+<div id='highlight'>
+<h4 class='heading'>
+doc.highlight(text)
+<a href="#highlight" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Performs basic Lua code highlighting.
+#### Parameters
+`text` **`string`**  
+ Code/text to do highlighting on.
+
+</div>
+
+<hr>
+<div id='renderCodeBlock'>
+<h4 class='heading'>
+doc.renderCodeBlock(text)
+<a href="#renderCodeBlock" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Assembles and renders a code block. This returns
+the supplied text based on the number of command line columns,
+and styles it to resemble a code block.
+#### Parameters
+`text` **`string`**  
+
+
+</div>
+

nature/dirs.lua

@@ -1,10 +1,12 @@
 -- @module dirs
+-- internal directory management
+-- The dirs module defines a small set of functions to store and manage
+-- directories.
 local fs = require 'fs'
 
 local dirs = {}
 
---- Last (current working) directory. Separate from recentDirs mainly for
+--- Last (current working) directory. Separate from recentDirs mainly for easier use.
---- easier use.
 dirs.old = ''
 --- Table of recent directories. For use, look at public functions.
 dirs.recentDirs = {}
@@ -35,13 +37,15 @@ function dirRecents(num, remove)
 end
 
 --- Look at `num` amount of recent directories, starting from the latest.
+--- This returns  a table of recent directories, up to the `num` amount.
 -- @param num? number
 function dirs.peak(num)
 	return dirRecents(num)
 end
 
---- Add `d` to the recent directories list.
+--- Add `dir` to the recent directories list.
-function dirs.push(d)
+--- @param dir string
+function dirs.push(dir)
 	dirs.recentDirs[dirs.recentSize + 1] = nil
 	if dirs.recentDirs[#dirs.recentDirs - 1] ~= d then
 		ok, d = pcall(fs.abs, d)

nature/doc.lua

@@ -1,13 +1,25 @@
+-- @module doc
+-- command-line doc rendering
+-- The doc module contains a small set of functions
+-- used by the Greenhouse pager to render parts of the documentation pages.
+-- This is only documented for the sake of it. It's only intended use
+-- is by the Greenhouse pager.
 local lunacolors = require 'lunacolors'
 
-local M = {}
+local doc = {}
 
-function M.highlight(text)
+--- Performs basic Lua code highlighting.
+--- @param text string Code/text to do highlighting on.
+function doc.highlight(text)
 	return text:gsub('\'.-\'', lunacolors.yellow)
 	--:gsub('%-%- .-', lunacolors.black)
 end
 
-function M.renderCodeBlock(text)
+--- Assembles and renders a code block. This returns
+--- the supplied text based on the number of command line columns,
+--- and styles it to resemble a code block.
+--- @param text string
+function doc.renderCodeBlock(text)
 	local longest = 0
 	local lines = string.split(text:gsub('\t', '    '), '\n')
 
@@ -17,14 +29,18 @@ function M.renderCodeBlock(text)
 	end
 
 	for i, line in ipairs(lines) do
-		lines[i] = lunacolors.format('{greyBg}' .. ' ' .. M.highlight(line:sub(0, longest))
+		lines[i] = lunacolors.format('{greyBg}' .. ' ' .. doc.highlight(line:sub(0, longest))
 		.. string.rep(' ', longest - line:len()) .. ' ')
 	end
 
 	return '\n' .. lunacolors.format('{greyBg}' .. table.concat(lines, '\n')) .. '\n'
 end
 
-function M.renderInfoBlock(type, text)
+--- Renders an info block. An info block is a block of text with
+--- an icon and styled text block.
+--- @param type string Type of info block. The only one specially styled is the `warning`.
+--- @param text string
+function doc.renderInfoBlock(type, text)
 	local longest = 0
 	local lines = string.split(text:gsub('\t', '    '), '\n')
 
@@ -34,7 +50,7 @@ function M.renderInfoBlock(type, text)
 	end
 
 	for i, line in ipairs(lines) do
-		lines[i] = ' ' .. M.highlight(line:sub(0, longest))
+		lines[i] = ' ' .. doc.highlight(line:sub(0, longest))
 		.. string.rep(' ', longest - line:len()) .. ' '
 	end
 
@@ -44,4 +60,4 @@ function M.renderInfoBlock(type, text)
 	end
 	return '\n' .. heading .. '\n' .. lunacolors.format('{greyBg}' .. table.concat(lines, '\n')) .. '\n'
 end
-return M
+return doc

nature/greenhouse/init.lua

@@ -1,4 +1,5 @@
--- Greenhouse is a simple text scrolling handler for terminal programs.
+-- @module greenhouse
+-- Greenhouse is a simple text scrolling handler (pager) for terminal programs.
 -- The idea is that it can be set a region to do its scrolling and paging
 -- job and then the user can draw whatever outside it.
 -- This reduces code duplication for the message viewer

nature/greenhouse/page.lua

@@ -1,3 +1,4 @@
+-- @module greenhouse.page
 local Object = require 'nature.object'
 
 local Page = Object:extend()
@@ -10,6 +11,7 @@ function Page:new(title, text)
 	self.children = {}
 end
 
+
 function Page:setText(text)
 	self.lines = string.split(text, '\n')
 end

nature/hummingbird.lua

@@ -1,3 +1,14 @@
+-- @module hilbish.messages
+-- simplistic message passing
+-- 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.
 local bait = require 'bait'
 local commander = require 'commander'
 local lunacolors = require 'lunacolors'
@@ -44,24 +55,30 @@ function hilbish.messages.send(message)
 	bait.throw('hilbish.notification', message)
 end
 
+--- Marks a message at `idx` as read.
+--- @param idx number
 function hilbish.messages.read(idx)
 	local msg = M._messages[idx]
-	if msg then
+	if msg then 
 		M._messages[idx].read = true
 		unread = unread - 1
 	end
 end
 
-function hilbish.messages.readAll(idx)
+--- Marks all messages as read.
+function hilbish.messages.readAll()
 	for _, msg in ipairs(hilbish.messages.all()) do
 		hilbish.messages.read(msg.index)
 	end
 end
 
+--- Returns the amount of unread messages.
 function hilbish.messages.unreadCount()
 	return unread
 end
 
+--- Deletes the message at `idx`.
+--- @param idx number
 function hilbish.messages.delete(idx)
 	local msg = M._messages[idx]
 	if not msg then
@@ -71,12 +88,14 @@ function hilbish.messages.delete(idx)
 	M._messages[idx] = nil
 end
 
+--- Deletes all messages.
 function hilbish.messages.clear()
 	for _, msg in ipairs(hilbish.messages.all()) do
 		hilbish.messages.delete(msg.index)
 	end
 end
 
+--- Returns all messages.
 function hilbish.messages.all()
 	return M._messages
 end

nature/runner.lua

@@ -1,4 +1,4 @@
---- hilbish.runner
+-- @module hilbish.runner
 local currentRunner = 'hybrid'
 local runners = {}
 
@@ -6,7 +6,7 @@ local runners = {}
 hilbish = hilbish
 
 --- Get a runner by name.
---- @param name string
+--- @param name string Name of the runner to retrieve.
 --- @return table
 function hilbish.runner.get(name)
 	local r = runners[name]
@@ -18,10 +18,10 @@ function hilbish.runner.get(name)
 	return r
 end
 
---- Adds a runner to the table of available runners. If runner is a table,
+--- Adds a runner to the table of available runners.
---- it must have the run function in it.
+--- If runner is a table, it must have the run function in it.
---- @param name string
+--- @param name string Name of the runner
---- @param runner function | table
+--- @param runner function|table 
 function hilbish.runner.add(name, runner)
 	if type(name) ~= 'string' then
 		error 'expected runner name to be a table'
@@ -42,7 +42,9 @@ function hilbish.runner.add(name, runner)
 	hilbish.runner.set(name, runner)
 end
 
---- Sets a runner by name. The runner table must have the run function in it.
+--- *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.
 --- @param name string
 --- @param runner table
 function hilbish.runner.set(name, runner)
@@ -53,11 +55,11 @@ function hilbish.runner.set(name, runner)
 	runners[name] = runner
 end
 
---- Executes cmd with a runner. If runnerName isn't passed, it uses
+--- Executes `cmd` with a runner.
---- the user's current runner.
+--- If `runnerName` is not specified, it uses the default Hilbish runner.
 --- @param cmd string
 --- @param runnerName string?
---- @return string, number, string
+--- @return table
 function hilbish.runner.exec(cmd, runnerName)
 	if not runnerName then runnerName = currentRunner end
 
@@ -66,7 +68,7 @@ function hilbish.runner.exec(cmd, runnerName)
 	return r.run(cmd)
 end
 
---- Sets the current interactive/command line runner mode.
+--- Sets Hilbish's runner mode by name.
 --- @param name string
 function hilbish.runner.setCurrent(name)
 	local r = hilbish.runner.get(name)