api.go

@@ -109,59 +109,70 @@ func hilbishLoad(rtm *rt.Runtime) (rt.Value, func()) {
 		username = strings.Split(username, "\\")[1] // for some reason Username includes the hostname on windows
 	}
 
-	util.SetFieldProtected(fakeMod, mod, "ver", rt.StringValue(getVersion()))
-	util.SetFieldProtected(fakeMod, mod, "user", rt.StringValue(username))
-	util.SetFieldProtected(fakeMod, mod, "host", rt.StringValue(host))
-	util.SetFieldProtected(fakeMod, mod, "home", rt.StringValue(curuser.HomeDir))
-	util.SetFieldProtected(fakeMod, mod, "dataDir", rt.StringValue(dataDir))
-	util.SetFieldProtected(fakeMod, mod, "interactive", rt.BoolValue(interactive))
-	util.SetFieldProtected(fakeMod, mod, "login", rt.BoolValue(login))
-	util.SetFieldProtected(fakeMod, mod, "vimMode", rt.NilValue)
-	util.SetFieldProtected(fakeMod, mod, "exitCode", rt.IntValue(0))
+	util.SetFieldProtected(fakeMod, mod, "ver", rt.StringValue(getVersion()), "Hilbish version")
+	util.SetFieldProtected(fakeMod, mod, "user", rt.StringValue(username), "Username of user")
+	util.SetFieldProtected(fakeMod, mod, "host", rt.StringValue(host), "Host name of the machine")
+	util.SetFieldProtected(fakeMod, mod, "home", rt.StringValue(curuser.HomeDir), "Home directory of the user")
+	util.SetFieldProtected(fakeMod, mod, "dataDir", rt.StringValue(dataDir), "Directory for Hilbish's data files")
+	util.SetFieldProtected(fakeMod, mod, "interactive", rt.BoolValue(interactive), "If this is an interactive shell")
+	util.SetFieldProtected(fakeMod, mod, "login", rt.BoolValue(login), "Whether this is a login shell")
+	util.SetFieldProtected(fakeMod, mod, "vimMode", rt.NilValue, "Current Vim mode of Hilbish (nil if not in Vim mode)")
+	util.SetFieldProtected(fakeMod, mod, "exitCode", rt.IntValue(0), "Exit code of last exected command")
+	util.Document(fakeMod, "Hilbish's core API, containing submodules and functions which relate to the shell itself.")
 
 	// hilbish.userDir table
 	hshuser := userDirLoader(rtm)
+	util.Document(hshuser, "User directories to store configs and/or modules.")
 	mod.Set(rt.StringValue("userDir"), rt.TableValue(hshuser))
 
 	// hilbish.os table
 	hshos := hshosLoader(rtm)
+	util.Document(hshos, "OS info interface")
 	mod.Set(rt.StringValue("os"), rt.TableValue(hshos))
 
 	// hilbish.aliases table
 	aliases = newAliases()
 	aliasesModule := aliases.Loader(rtm)
+	util.Document(aliasesModule, "Alias inferface for Hilbish.")
 	mod.Set(rt.StringValue("aliases"), rt.TableValue(aliasesModule))
 
 	// hilbish.history table
 	historyModule := lr.Loader(rtm)
 	mod.Set(rt.StringValue("history"), rt.TableValue(historyModule))
+	util.Document(historyModule, "History interface for Hilbish.")
 
 	// hilbish.completion table
 	hshcomp := completionLoader(rtm)
+	util.Document(hshcomp, "Completions interface for Hilbish.")
 	mod.Set(rt.StringValue("completion"), rt.TableValue(hshcomp))
 
 	// hilbish.runner table
 	runnerModule := runnerModeLoader(rtm)
+	util.Document(runnerModule, "Runner/exec interface for Hilbish.")
 	mod.Set(rt.StringValue("runner"), rt.TableValue(runnerModule))
 
 	// hilbish.jobs table
 	jobs = newJobHandler()
 	jobModule := jobs.loader(rtm)
+	util.Document(jobModule, "(Background) job interface.")
 	mod.Set(rt.StringValue("jobs"), rt.TableValue(jobModule))
 
 	// hilbish.timers table
 	timers = newTimersModule()
 	timersModule := timers.loader(rtm)
+	util.Document(timersModule, "Timer interface, for control of all intervals and timeouts.")
 	mod.Set(rt.StringValue("timers"), rt.TableValue(timersModule))
 
 	editorModule := editorLoader(rtm)
+	util.Document(editorModule, "")
 	mod.Set(rt.StringValue("editor"), rt.TableValue(editorModule))
 
 	versionModule := rt.NewTable()
-	util.SetField(rtm, versionModule, "branch", rt.StringValue(gitBranch))
-	util.SetField(rtm, versionModule, "full", rt.StringValue(getVersion()))
-	util.SetField(rtm, versionModule, "commit", rt.StringValue(gitCommit))
-	util.SetField(rtm, versionModule, "release", rt.StringValue(releaseName))
+	util.SetField(rtm, versionModule, "branch", rt.StringValue(gitBranch), "Git branch Hilbish was compiled from")
+	util.SetField(rtm, versionModule, "full", rt.StringValue(getVersion()), "Full version info, including release name")
+	util.SetField(rtm, versionModule, "commit", rt.StringValue(gitCommit), "Git commit Hilbish was compiled from")
+	util.SetField(rtm, versionModule, "release", rt.StringValue(releaseName), "Release name")
+	util.Document(versionModule, "Version info interface.")
 	mod.Set(rt.StringValue("version"), rt.TableValue(versionModule))
 
 	return rt.TableValue(fakeMod), nil
@@ -176,12 +187,12 @@ func getenv(key, fallback string) string {
 }
 
 func setVimMode(mode string) {
-	util.SetField(l, hshMod, "vimMode", rt.StringValue(mode))
+	util.SetField(l, hshMod, "vimMode", rt.StringValue(mode), "Current Vim mode of Hilbish (nil if not in Vim mode)")
 	hooks.Emit("hilbish.vimMode", mode)
 }
 
 func unsetVimMode() {
-	util.SetField(l, hshMod, "vimMode", rt.NilValue)
+	util.SetField(l, hshMod, "vimMode", rt.NilValue, "Current Vim mode of Hilbish (nil if not in Vim mode)")
 }
 
 // run(cmd, returnOut) -> exitCode, stdout, stderr

docs/api/_index.md

@@ -5,4 +5,3 @@ weight: -50
 menu: docs
 ---
 
-Hello!

docs/api/index.md

@@ -1 +0,0 @@
-hello!

exec.go

@@ -552,7 +552,7 @@ func splitInput(input string) ([]string, string) {
 }
 
 func cmdFinish(code uint8, cmdstr string, private bool) {
-	util.SetField(l, hshMod, "exitCode", rt.IntValue(int64(code)))
+	util.SetField(l, hshMod, "exitCode", rt.IntValue(int64(code)), "Exit code of last exected command")
 	// using AsValue (to convert to lua type) on an interface which is an int
 	// results in it being unknown in lua .... ????
 	// so we allow the hook handler to take lua runtime Values

golibs/bait/bait.go

@@ -204,6 +204,15 @@ func (b *Bait) loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
 	mod := rt.NewTable()
 	util.SetExports(rtm, mod, exports)
 
+	util.Document(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. To find all available hooks, see doc hooks.`)
+
 	return rt.TableValue(mod), nil
 }
 

golibs/commander/commander.go

@@ -34,6 +34,7 @@ func (c *Commander) loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
 	}
 	mod := rt.NewTable()
 	util.SetExports(rtm, mod, exports)
+	util.Document(mod, "Commander is Hilbish's custom command library, a way to write commands in Lua.")
 
 	return rt.TableValue(mod), nil
 }

golibs/fs/fs.go

@@ -39,6 +39,10 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
 	mod.Set(rt.StringValue("pathSep"), rt.StringValue(string(os.PathSeparator)))
 	mod.Set(rt.StringValue("pathListSep"), rt.StringValue(string(os.PathListSeparator)))
 
+	util.Document(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 filesystem functions.`)
+
 	return rt.TableValue(mod), nil
 }
 

golibs/terminal/terminal.go

@@ -28,6 +28,7 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
 
 	mod := rt.NewTable()
 	util.SetExports(rtm, mod, exports)
+	util.Document(mod, "The terminal library is a simple and lower level library for certain terminal interactions.")
 
 	return rt.TableValue(mod), nil
 }

nature/commands/doc.lua

@@ -15,34 +15,32 @@ commander.register('doc', function(args)
 
 		local f = io.open(moddocPath .. mod .. '.md', 'rb')
 		local funcdocs = nil
-		local subdocName = args[2]
 		if not f then
 			-- assume subdir
 			-- dataDir/docs/<mod>/<mod>.md
 			moddocPath = moddocPath .. mod .. '/'
+			local subdocName = args[2]
 			if not subdocName then
-				subdocName = '_index'
+				subdocName = 'index'
 			end
 			f = io.open(moddocPath .. subdocName .. '.md', 'rb')
-			if not f then
-				moddocPath = moddocPath .. subdocName .. '/'
-				subdocName = args[3] or '_index'
-				f = io.open(moddocPath .. subdocName .. '.md', 'rb')
-			end
 			if not f then
 				print('No documentation found for ' .. mod .. '.')
 				return
 			end
-		end
-		funcdocs = f:read '*a':gsub('-([%d]+)', '%1')
-		local moddocs = table.filter(fs.readdir(moddocPath), function(f) return f ~= '_index.md' end)
-		local subdocs = table.map(moddocs, function(fname)
-			return lunacolors.underline(lunacolors.blue(string.gsub(fname, '.md', '')))
-		end)
-		if subdocName == '_index' then
-			funcdocs = funcdocs .. '\nSubdocs: ' .. table.concat(subdocs, ', ')
+			funcdocs = f:read '*a'
+			local moddocs = table.filter(fs.readdir(moddocPath), function(f) return f ~= 'index.md' end)
+			local subdocs = table.map(moddocs, function(fname)
+				return lunacolors.underline(lunacolors.blue(string.gsub(fname, '.md', '')))
+			end)
+			if subdocName == 'index' then
+				funcdocs = funcdocs .. '\nSubdocs: ' .. table.concat(subdocs, ', ')
+			end
 		end
 
+		if not funcdocs then
+			funcdocs = f:read '*a'
+		end
 		local valsStr = funcdocs:match '%-%-%-\n([^%-%-%-]+)\n'
 		local vals = {}
 		if valsStr then
@@ -55,13 +53,11 @@ commander.register('doc', function(args)
 				local key = line:match '(%w+): '
 				local val = line:match '^%w+: (.-)$'
 
-				if key then
-					vals[key] = val
-				end
+				vals[key] = val
 			end
 		end
 		if mod == 'api' then
-			funcdocs = string.format(apidocHeader, vals.title, vals.description or 'no description.') .. funcdocs
+			funcdocs = string.format(apidocHeader, vals.name, vals.description) .. funcdocs
 		end
 		local backtickOccurence = 0
 		local formattedFuncs = lunacolors.format(funcdocs:sub(1, #funcdocs - 1):gsub('`', function()

os.go

@@ -19,9 +19,9 @@ func hshosLoader(rtm *rt.Runtime) *rt.Table {
 	info, _ := osinfo.GetOSInfo()
 	mod := rt.NewTable()
 
-	util.SetField(rtm, mod, "family", rt.StringValue(info.Family))
-	util.SetField(rtm, mod, "name", rt.StringValue(info.Name))
-	util.SetField(rtm, mod, "version", rt.StringValue(info.Version))
+	util.SetField(rtm, mod, "family", rt.StringValue(info.Family), "Family name of the current OS")
+	util.SetField(rtm, mod, "name", rt.StringValue(info.Name), "Pretty name of the current OS")
+	util.SetField(rtm, mod, "version", rt.StringValue(info.Version), "Version of the current OS")
 
 	return mod
 }

userdir.go

@@ -16,8 +16,8 @@ import (
 func userDirLoader(rtm *rt.Runtime) *rt.Table {
 	mod := rt.NewTable()
 
-	util.SetField(rtm, mod, "config", rt.StringValue(confDir))
-	util.SetField(rtm, mod, "data", rt.StringValue(userDataDir))
+	util.SetField(rtm, mod, "config", rt.StringValue(confDir), "User's config directory")
+	util.SetField(rtm, mod, "data", rt.StringValue(userDataDir), "XDG data directory")
 
 	return mod
 }

util/util.go

@@ -10,18 +10,53 @@ import (
 	rt "github.com/arnodel/golua/runtime"
 )
 
+// Document adds a documentation string to a module.
+// It is accessible via the __doc metatable.
+func Document(module *rt.Table, doc string) {
+	mt := module.Metatable()
+	
+	if mt == nil {
+		mt = rt.NewTable()
+		module.SetMetatable(mt)
+	}
+
+	mt.Set(rt.StringValue("__doc"), rt.StringValue(doc))
+}
+
 // SetField sets a field in a table, adding docs for it.
 // It is accessible via the __docProp metatable. It is a table of the names of the fields.
-func SetField(rtm *rt.Runtime, module *rt.Table, field string, value rt.Value) {
+func SetField(rtm *rt.Runtime, module *rt.Table, field string, value rt.Value, doc string) {
 	// TODO:    ^ rtm isnt needed, i should remove it
+	SetFieldDoc(module, field, doc)
 	module.Set(rt.StringValue(field), value)
 }
 
+// SetFieldDoc sets the __docProp metatable for a field on the
+// module.
+func SetFieldDoc(module *rt.Table, field, doc string) {
+	mt := module.Metatable()
+
+	if mt == nil {
+		mt = rt.NewTable()
+		module.SetMetatable(mt)
+	}
+
+	docProp := mt.Get(rt.StringValue("__docProp"))
+	if docProp == rt.NilValue {
+		docPropTbl := rt.NewTable()
+		mt.Set(rt.StringValue("__docProp"), rt.TableValue(docPropTbl))
+		docProp = mt.Get(rt.StringValue("__docProp"))
+	}
+
+	docProp.AsTable().Set(rt.StringValue(field), rt.StringValue(doc))
+}
+
 // SetFieldProtected sets a field in a protected table. A protected table
 // is one which has a metatable proxy to ensure no overrides happen to it.
 // It sets the field in the table and sets the __docProp metatable on the
 // user facing table.
-func SetFieldProtected(module, realModule *rt.Table, field string, value rt.Value) {
+func SetFieldProtected(module, realModule *rt.Table, field string, value rt.Value, doc string) {
+	SetFieldDoc(module, field, doc)
 	realModule.Set(rt.StringValue(field), value)
 }