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

.gitignore

@@ -1,5 +1,6 @@
 *.exe
 hilbish
+docgen
 
 .vim
 petals/

cmd/docgen/docgen.go

@@ -0,0 +1,79 @@
+package main
+
+import (
+	"fmt"
+	"path/filepath"
+	"go/ast"
+	"go/doc"
+	"go/parser"
+	"go/token"
+	"strings"
+	"os"
+)
+
+// feel free to clean this up
+// it works, dont really care about the code
+func main() {
+	fset := token.NewFileSet()
+
+	dirs := []string{"./"}
+	filepath.Walk("golibs/", func (path string, info os.FileInfo, err error) error {
+		if !info.IsDir() {
+			return nil
+		}
+		dirs = append(dirs, "./" + path)
+		return nil
+	})
+
+	pkgs := make(map[string]*ast.Package)
+	for _, path := range dirs {
+		d, err := parser.ParseDir(fset, path, nil, parser.ParseComments)
+		if err != nil {
+			fmt.Println(err)
+			return
+		}
+		for k, v := range d {
+			pkgs[k] = v
+		}
+	}
+
+	prefix := map[string]string{
+		"main": "hsh",
+		"hilbish": "hl",
+		"fs": "f",
+		"commander": "c",
+		"bait": "b",
+	}
+	docs := make(map[string][]string)
+
+	for l, f := range pkgs {
+		p := doc.New(f, "./", doc.AllDecls)
+		for _, t := range p.Funcs {
+			mod := l
+			if strings.HasPrefix(t.Name, "hl") { mod = "hilbish" }
+			if !strings.HasPrefix(t.Name, prefix[mod]) || t.Name == "Loader" { continue }
+			parts := strings.Split(t.Doc, "\n")
+			funcsig := parts[0]
+			doc := parts[1:]
+
+			docs[mod] = append(docs[mod], funcsig + " > " + strings.Join(doc, "\n"))
+		}
+		for _, t := range p.Types {
+			for _, m := range t.Methods {
+				if !strings.HasPrefix(m.Name, prefix[l]) || m.Name == "Loader" { continue }
+				parts := strings.Split(m.Doc, "\n")
+				funcsig := parts[0]
+				doc := parts[1:]
+
+				docs[l] = append(docs[l], funcsig + " > " + strings.Join(doc, "\n"))
+			}
+		}
+	}
+
+	for mod, v := range docs {
+		if mod == "main" { mod = "global" }
+		os.Mkdir("docs", 0744)
+		f, _ := os.Create("docs/" + mod + ".txt")
+		f.WriteString(strings.Join(v, "\n") + "\n")
+	}
+}

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"
@@ -18,18 +20,24 @@ func New() Bait {
 
 func (b *Bait) Loader(L *lua.LState) int {
 	mod := L.SetFuncs(L.NewTable(), map[string]lua.LGFunction{})
-	L.SetField(mod, "throw", luar.New(L, b.throw))
+	L.SetField(mod, "throw", luar.New(L, b.bthrow))
-	L.SetField(mod, "catch", luar.New(L, b.catch))
+	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
 }
 
-func (b *Bait) throw(name string, args ...interface{}) {
+// throw(name, ...args)
+// Throws a hook with `name` with the provided `args`
+func (b *Bait) bthrow(name string, args ...interface{}) {
 	b.Em.Emit(name, args...)
 }
 
-func (b *Bait) catch(name string, catcher func(...interface{})) {
+// catch(name, cb)
+// Catches a hook with `name`. Runs the `cb` when it is thrown
+func (b *Bait) bcatch(name string, catcher func(...interface{})) {
 	b.Em.On(name, catcher)
 }

golibs/commander/commander.go

@@ -1,6 +1,8 @@
 package commander
 
 import (
+	"hilbish/util"
+
 	"github.com/chuckpreslar/emission"
 	"github.com/yuin/gopher-lua"
 )
@@ -17,17 +19,19 @@ func New() Commander {
 
 func (c *Commander) Loader(L *lua.LState) int {
 	var exports = map[string]lua.LGFunction{
-		"register": c.register,
+		"register": c.cregister,
-		"deregister": c.deregister,
+		"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
 }
 
-func (c *Commander) register(L *lua.LState) int {
+// register(name, cb)
+// Register a command with `name` that runs `cb` when ran
+func (c *Commander) cregister(L *lua.LState) int {
 	cmdName := L.CheckString(1)
 	cmd := L.CheckFunction(2)
 
@@ -36,7 +40,9 @@ func (c *Commander) register(L *lua.LState) int {
 	return 0
 }
 
-func (c *Commander) deregister(L *lua.LState) int {
+// deregister(name)
+// Deregisters any command registered with `name`
+func (c *Commander) cderegister(L *lua.LState) int {
 	cmdName := L.CheckString(1)
 
 	c.Events.Emit("commandDeregister", cmdName)

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,42 +15,49 @@ 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
 }
 
-func LuaErr(L *lua.LState, code int) {
+func luaErr(L *lua.LState, code int) {
 	// TODO: Error with a table, with path and error code
 	L.Error(lua.LNumber(code), 2)
 }
 
 var exports = map[string]lua.LGFunction{
-	"cd": cd,
+	"cd": fcd,
-	"mkdir": mkdir,
+	"mkdir": fmkdir,
-	"stat": stat,
+	"stat": fstat,
 }
 
-func cd(L *lua.LState) int {
+// cd(dir)
+// Changes directory to `dir`
+func fcd(L *lua.LState) int {
 	path := L.CheckString(1)
 
 	err := os.Chdir(strings.TrimSpace(path))
 	if err != nil {
 		switch e := err.(*os.PathError).Err.Error(); e {
 		case "no such file or directory":
-			LuaErr(L, 1)
+			luaErr(L, 1)
 		case "not a directory":
-			LuaErr(L, 2)
+			luaErr(L, 2)
 		default:
 			fmt.Printf("Found unhandled error case: %s\n", e)
 			fmt.Printf("Report this at https://github.com/Rosettea/Hilbish/issues with the title being: \"fs: unhandled error case %s\", and show what caused it.\n", e)
-			LuaErr(L, 213)
+			luaErr(L, 213)
 		}
 	}
 
 	return 0
 }
 
-func mkdir(L *lua.LState) int {
+// mkdir(name, recursive)
+// Makes a directory called `name`. If `recursive` is true, it will create its parent directories.
+func fmkdir(L *lua.LState) int {
 	dirname := L.CheckString(1)
 	recursive := L.ToBool(2)
 	path := strings.TrimSpace(dirname)
@@ -62,7 +72,9 @@ func mkdir(L *lua.LState) int {
 	return 0
 }
 
-func stat(L *lua.LState) int {
+// stat(path)
+// Returns info about `path`
+func fstat(L *lua.LState) int {
 	path := L.CheckString(1)
 
 	// TODO: handle error here

hilbish.go

@@ -14,9 +14,9 @@ import (
 )
 
 var exports = map[string]lua.LGFunction {
-	"run": run,
+	"run": hlrun,
-	"flag": flag,
+	"flag": hlflag,
-	"cwd": cwd,
+	"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))
+	setField(L, mod, "ver", lua.LString(version), "The version of Hilbish")
-	L.SetField(mod, "user", lua.LString(username))
+	setField(L, mod, "user", lua.LString(username), "Current user's username")
-	L.SetField(mod, "host", lua.LString(host))
+	setField(L, mod, "host", lua.LString(host), "Hostname of the system")
-	L.SetField(mod, "home", lua.LString(homedir))
+	setField(L, mod, "home", lua.LString(homedir), "Path of home directory")
 
 	xdg := L.NewTable()
-	L.SetField(xdg, "config", lua.LString(confDir))
+	setField(L, xdg, "config", lua.LString(confDir), "XDG config directory")
-	L.SetField(xdg, "data", lua.LString(getenv("XDG_DATA_HOME", homedir + "/.local/share/")))
+	setField(L, xdg, "data", lua.LString(getenv("XDG_DATA_HOME", homedir + "/.local/share/")), "XDG data directory")
-	L.SetField(mod, "xdg", xdg)
+	setField(L, mod, "xdg", xdg, "XDG values for Linux")
 
 	L.Push(mod)
 
 	return 1
 }
 
-// Runs a command
+// run(cmd)
-func run(L *lua.LState) int {
+// 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,18 +96,36 @@ func RunLogin() {
 	}
 }
 
+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)
 
 	return 0
 }
 
+// multiprompt(str)
+// Changes the continued line prompt to `str`
 func hshmlprompt(L *lua.LState) int {
 	multilinePrompt = L.CheckString(1)
 
 	return 0
 }
 
+// alias(cmd, orig)
+// Sets an alias of `orig` to `cmd`
 func hshalias(L *lua.LState) int {
 	alias := L.CheckString(1)
 	source := L.CheckString(2)
@@ -116,6 +135,8 @@ func hshalias(L *lua.LState) int {
 	return 1
 }
 
+// appendPath(dir)
+// Appends `dir` to $PATH
 func hshappendPath(L *lua.LState) int {
 	dir := L.CheckString(1)
 	dir = strings.Replace(dir, "~", curuser.HomeDir, 1)
@@ -129,6 +150,8 @@ func hshappendPath(L *lua.LState) int {
 	return 0
 }
 
+// exec(cmd)
+// Replaces running hilbish with `cmd`
 func hshexec(L *lua.LState) int {
 	cmd := L.CheckString(1)
 	cmdArgs, _ := splitInput(cmd)
@@ -146,16 +169,22 @@ func hshexec(L *lua.LState) int {
 	return 0 // random thought: does this ever return?
 }
 
+// goro(fn)
+// Puts `fn` in a goroutine
 func hshgoroutine(gofunc func()) {
 	go gofunc()
 }
 
+// timeout(cb, time)
+// Runs the `cb` function after `time` in milliseconds
 func hshtimeout(timeoutfunc func(), ms int) {
 	timeout := time.Duration(ms) * time.Millisecond
 	time.Sleep(timeout)
 	timeoutfunc()
 }
 
+// interval(cb, time)
+// Runs the `cb` function every `time` milliseconds
 func hshinterval(L *lua.LState) int {
 	intervalfunc := L.CheckFunction(1)
 	ms := L.CheckInt(2)

rl.go

@@ -1,9 +1,10 @@
 // +build !hilbiline
 
+package main
+
 // Here we define a generic interface for readline and hilbiline,
 // making them interchangable during build time
 // this is normal readline
-package main
 
 import "github.com/bobappleyard/readline"
 

rl_hilbiline.go

@@ -1,9 +1,10 @@
 // +build hilbiline
 
+package main
+
 // Here we define a generic interface for readline and hilbiline,
 // making them interchangable during build time
 // this is hilbiline's, as is obvious by the filename
-package main
 
 import "github.com/Rosettea/Hilbiline"
 

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