docs: add more detailed documentation for lua modules

docs/api/hilbish/hilbish.messages.md

@@ -1316,3 +1316,211 @@ hilbish.messages.unreadCount()
 This function has no parameters.  
 </div>
 
+<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>
+
+<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,11 +57,11 @@ 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. If runnerName isn't passed, it uses|
+|<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 runner table must have the run function in it.|
+|<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. If runner is a table,|
+|<a href="#add">add(name, runner)</a>|Adds a runner to the table of available runners.|
-|<a href="#setCurrent">setCurrent(name)</a>|Sets the current interactive/command line runner mode.|
+|<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>
@@ -143,7 +143,7 @@ hilbish.runner.setCurrent(name)
 </a>
 </h4>
 
-Sets the current interactive/command line runner mode.
+Sets Hilbish's runner mode by name.
 #### Parameters
 `name` **`string`**  
 
@@ -159,14 +159,14 @@ hilbish.runner.add(name, runner)
 </a>
 </h4>
 
-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.
 #### Parameters
 `name` **`string`**  
-
+ Name of the runner
 
 `runner` **`function|table`**  
-
+ 
 
 </div>
 
@@ -182,7 +182,7 @@ hilbish.runner.get(name)
 Get a runner by name.
 #### Parameters
 `name` **`string`**  
-
+ Name of the runner to retrieve.
 
 </div>
 
@@ -195,7 +195,9 @@ hilbish.runner.set(name, runner)
 </a>
 </h4>
 
-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.
 #### Parameters
 `name` **`string`**  
 
@@ -214,8 +216,8 @@ hilbish.runner.exec(cmd, runnerName)
 </a>
 </h4>
 
-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.
 #### Parameters
 `cmd` **`string`**  
 

docs/nature/dirs.md

@@ -26,15 +26,17 @@ Sets the old directory string.
 <hr>
 <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>
@@ -47,6 +49,7 @@ 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`**  
 

docs/nature/doc.md

@@ -0,0 +1,63 @@
+---
+title: Module doc
+description: No description.
+layout: doc
+menu:
+  docs:
+    parent: "Nature"
+---
+
+<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,4 +1,7 @@
 -- @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 = {}
@@ -35,13 +38,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,4 +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'
@@ -45,6 +55,8 @@ 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 
@@ -53,17 +65,20 @@ function hilbish.messages.read(idx)
 	end
 end
 
+--- 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
@@ -73,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

@@ -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)