docs: document `hilbish` module functions, xdg vars, and add descriptions for modules

golibs/bait/bait.go

@@ -1,6 +1,8 @@
 package bait
 
 import (
+	"hilbish/util"
+
 	"github.com/chuckpreslar/emission"
 	"github.com/yuin/gopher-lua"
 	"layeh.com/gopher-luar"
@@ -21,6 +23,8 @@ func (b *Bait) Loader(L *lua.LState) int {
 	L.SetField(mod, "throw", luar.New(L, b.bthrow))
 	L.SetField(mod, "catch", luar.New(L, b.bcatch))
 
+	util.Document(L, mod, `Bait is the event emitter for Hilbish. Why name it bait? Because it throws hooks that you can catch. (emits events that you can listen to) and because why not, fun naming is fun.
+This is what you will use if you want to listen in on hooks to know when certain things have happened, like when you've changed directory, a command has failed, etc.`)
 	L.Push(mod)
 
 	return 1

golibs/commander/commander.go

@@ -1,6 +1,8 @@
 package commander
 
 import (
+	"hilbish/util"
+
 	"github.com/chuckpreslar/emission"
 	"github.com/yuin/gopher-lua"
 )
@@ -21,7 +23,7 @@ func (c *Commander) Loader(L *lua.LState) int {
 		"deregister": c.cderegister,
 	}
 	mod := L.SetFuncs(L.NewTable(), exports)
-
+	util.Document(L, mod, "Commander is Hilbish's custom command library, a way to write commands with the shell in Lua.")
 	L.Push(mod)
 
 	return 1

golibs/fs/fs.go

@@ -1,3 +1,5 @@
+// The fs module provides easy and simple access to filesystem functions and other
+// things, and acts an addition to the Lua standard library's I/O and fs functions.
 package fs
 
 import (
@@ -5,6 +7,7 @@ import (
 	"os"
 	"strings"
 
+	"hilbish/util"
 	"github.com/yuin/gopher-lua"
 	"layeh.com/gopher-luar"
 )
@@ -12,6 +15,9 @@ import (
 func Loader(L *lua.LState) int {
 	mod := L.SetFuncs(L.NewTable(), exports)
 
+	util.Document(L, mod, `The fs module provides easy and simple access to filesystem functions and other
+things, and acts an addition to the Lua standard library's I/O and fs functions.`)
+
 	L.Push(mod)
 	return 1
 }

hilbish.go

@@ -14,9 +14,9 @@ import (
 )
 
 var exports = map[string]lua.LGFunction {
-	"run": run,
-	"flag": flag,
-	"cwd": cwd,
+	"run": hlrun,
+	"flag": hlflag,
+	"cwd": hlcwd,
 }
 
 func HilbishLoader(L *lua.LState) int {
@@ -29,23 +29,24 @@ func HilbishLoader(L *lua.LState) int {
 		username = strings.Split(username, "\\")[1] // for some reason Username includes the hostname on windows
 	}
 
-	L.SetField(mod, "ver", lua.LString(version))
-	L.SetField(mod, "user", lua.LString(username))
-	L.SetField(mod, "host", lua.LString(host))
-	L.SetField(mod, "home", lua.LString(homedir))
+	setField(L, mod, "ver", lua.LString(version), "The version of Hilbish")
+	setField(L, mod, "user", lua.LString(username), "Current user's username")
+	setField(L, mod, "host", lua.LString(host), "Hostname of the system")
+	setField(L, mod, "home", lua.LString(homedir), "Path of home directory")
 
 	xdg := L.NewTable()
-	L.SetField(xdg, "config", lua.LString(confDir))
-	L.SetField(xdg, "data", lua.LString(getenv("XDG_DATA_HOME", homedir + "/.local/share/")))
-	L.SetField(mod, "xdg", xdg)
+	setField(L, xdg, "config", lua.LString(confDir), "XDG config directory")
+	setField(L, xdg, "data", lua.LString(getenv("XDG_DATA_HOME", homedir + "/.local/share/")), "XDG data directory")
+	setField(L, mod, "xdg", xdg, "XDG values for Linux")
 
 	L.Push(mod)
 
 	return 1
 }
 
-// Runs a command
-func run(L *lua.LState) int {
+// run(cmd)
+// Runs `cmd` in Hilbish's sh interpreter
+func hlrun(L *lua.LState) int {
 	var exitcode uint8 = 0
 	cmd := L.CheckString(1)
 	err := execCommand(cmd)
@@ -60,7 +61,9 @@ func run(L *lua.LState) int {
 	return 1
 }
 
-func flag(L *lua.LState) int {
+// flag(f)
+// Checks if the `f` flag has been passed to Hilbish.
+func hlflag(L *lua.LState) int {
 	flagchar := L.CheckString(1)
 
 	L.Push(lua.LBool(getopt.Lookup([]rune(flagchar)[0]).Seen()))
@@ -68,7 +71,9 @@ func flag(L *lua.LState) int {
 	return 1
 }
 
-func cwd(L *lua.LState) int {
+// cwd()
+// Returns the current directory of the shell
+func hlcwd(L *lua.LState) int {
 	cwd, _ := os.Getwd()
 
 	L.Push(lua.LString(cwd))

lua.go

@@ -8,6 +8,7 @@ import (
 	"syscall"
 	"time"
 
+	"hilbish/util"
 	"hilbish/golibs/bait"
 	"hilbish/golibs/commander"
 	"hilbish/golibs/fs"
@@ -95,8 +96,20 @@ func RunLogin() {
 	}
 }
 
-// prompt(str)
-// Changes the shell prompt to `str`
+func setField(L *lua.LState, module lua.LValue, name string, val lua.LValue, doc string) {
+	if val.Type() == lua.LTTable {
+		util.Document(L, module, doc)
+   }
+	L.SetField(module, name, val)
+}
+
+/* prompt(str)
+Changes the shell prompt to `str`
+There are a few verbs that can be used in the prompt text.
+These will be formatted and replaced with the appropriate values.
+`%d` - Current working directory
+`%u` - Name of current user
+`%h` - Hostname of device */
 func hshprompt(L *lua.LState) int {
 	prompt = L.CheckString(1)
 

util/util.go

@@ -0,0 +1,10 @@
+package util
+
+import "github.com/yuin/gopher-lua"
+
+func Document(L *lua.LState, module lua.LValue, doc string) {
+	mt := L.NewTable()
+	L.SetField(mt, "__doc", lua.LString(doc))
+
+	L.SetMetatable(module, mt)
+}