feat: add docgen program, document almost all hilbish functions

.gitignore

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

cmd/docgen/docgen.go

@@ -2,26 +2,66 @@ package main
 
 import (
 	"fmt"
+	"path/filepath"
+	"go/ast"
 	"go/doc"
 	"go/parser"
 	"go/token"
+	"strings"
+	"os"
 )
 
 func main() {
 	fset := token.NewFileSet()
 
-	d, err := parser.ParseDir(fset, "./", nil, parser.ParseComments)
+	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
+		}
+	}
 
-	for _, f := range d {
-		p := doc.New(f, "./", 0)
+	prefix := map[string]string{
+		"main": "hsh",
+		"fs": "f",
+		"commander": "c",
+		"bait": "b",
+	}
 
+	for l, f := range pkgs {
+		fmt.Println("------", l)
+		p := doc.New(f, "./", doc.AllDecls)
 		for _, t := range p.Funcs {
-			fmt.Println("	type", t.Name)
-			fmt.Println("		docs:", t.Doc)
+			if !strings.HasPrefix(t.Name, prefix[l]) || t.Name == "Loader" { continue }
+			parts := strings.Split(t.Doc, "\n")
+			funcsig := parts[0]
+			doc := parts[1]
+
+			fmt.Println(funcsig, ">", doc)
+		}
+		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]
+
+				fmt.Println(funcsig, ">", doc)
+			}
 		}
 	}
 }

golibs/bait/bait.go

@@ -18,18 +18,22 @@ 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, "catch", luar.New(L, b.catch))
+	L.SetField(mod, "throw", luar.New(L, b.bthrow))
+	L.SetField(mod, "catch", luar.New(L, b.bcatch))
 
 	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

@@ -17,8 +17,8 @@ func New() Commander {
 
 func (c *Commander) Loader(L *lua.LState) int {
 	var exports = map[string]lua.LGFunction{
-		"register": c.register,
-		"deregister": c.deregister,
+		"register": c.cregister,
+		"deregister": c.cderegister,
 	}
 	mod := L.SetFuncs(L.NewTable(), exports)
 
@@ -27,7 +27,9 @@ func (c *Commander) Loader(L *lua.LState) int {
 	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 +38,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

@@ -16,38 +16,42 @@ func Loader(L *lua.LState) int {
 	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,
-	"mkdir": mkdir,
-	"stat": stat,
+	"cd": fcd,
+	"mkdir": fmkdir,
+	"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 +66,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

lua.go

@@ -95,18 +95,24 @@ func RunLogin() {
 	}
 }
 
+// prompt(str)
+// Changes the shell prompt to `str`
 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 +122,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 +137,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 +156,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)