docs: add hilbish.jobs docs, distinguish between properties and fields

cmd/docgen/docgen.go

@@ -29,6 +29,7 @@ type emmyPiece struct {
 
 type module struct {
 	Docs []docPiece
+	Fields []docPiece
 	Properties []docPiece
 	ShortDescription string
 	Description string
@@ -45,6 +46,7 @@ type docPiece struct {
 	GoFuncName string
 	IsInterface bool
 	IsMember bool
+	Fields []docPiece
 	Properties []docPiece
 }
 
@@ -116,7 +118,15 @@ func setupDoc(mod string, fun *doc.Func) *docPiece {
 	}
 	em := emmyPiece{FuncName: funcName}
 
-	// manage properties
+	// manage fields
+	fields := []docPiece{}
+	for _, tag := range tags["field"] {
+		fields = append(fields, docPiece{
+			FuncName: tag.id,
+			Doc: tag.fields,
+		})
+	}
+
 	properties := []docPiece{}
 	for _, tag := range tags["property"] {
 		properties = append(properties, docPiece{
@@ -159,6 +169,7 @@ func setupDoc(mod string, fun *doc.Func) *docPiece {
 		IsInterface: inInterface,
 		IsMember: isMember,
 		ParentModule: parentMod,
+		Fields: fields,
 		Properties: properties,
 	}
 	if strings.HasSuffix(dps.GoFuncName, strings.ToLower("loader")) {
@@ -253,6 +264,7 @@ func main() {
 				desc := piece.Doc[1:]
 				interfaceModules[modname].ShortDescription = shortDesc
 				interfaceModules[modname].Description = strings.Join(desc, "\n")
+				interfaceModules[modname].Fields = piece.Fields
 				interfaceModules[modname].Properties = piece.Properties
 				continue
 			}
@@ -295,13 +307,23 @@ func main() {
 			f, _ := os.Create(docPath)
 			f.WriteString(fmt.Sprintf(header, modOrIface, modname, modu.ShortDescription))
 			f.WriteString(fmt.Sprintf("## Introduction\n%s\n\n", modu.Description))
+			if len(modu.Fields) != 0 {
+				f.WriteString("## Interface fields\n")
+				for _, dps := range modu.Fields {
+					f.WriteString(fmt.Sprintf("- `%s`: ", dps.FuncName))
+					f.WriteString(strings.Join(dps.Doc, " "))
+					f.WriteString("\n")
+				}
+				f.WriteString("\n")
+			}
 			if len(modu.Properties) != 0 {
-				f.WriteString("## Properties\n")
+				f.WriteString("## Object properties\n")
 				for _, dps := range modu.Properties {
 					f.WriteString(fmt.Sprintf("- `%s`: ", dps.FuncName))
 					f.WriteString(strings.Join(dps.Doc, " "))
 					f.WriteString("\n")
 				}
+				f.WriteString("\n")
 			}
 			if len(modu.Docs) != 0 {
 				f.WriteString("## Functions\n")

docs/api/hilbish/hilbish.jobs.md

@@ -0,0 +1,50 @@
+---
+name: Interface hilbish.jobs
+description: background job management
+layout: apidoc
+---
+
+## Introduction
+ Manage interactive jobs in Hilbish via Lua.
+
+Jobs are the name of background tasks/commands. A job can be started via
+interactive usage or with the functions defined below for use in external runners.
+
+## Object properties
+- `cmd`: The user entered command string for the job.
+- `running`: Whether the job is running or not.
+- `id`: The ID of the job in the job table
+- `pid`: The Process ID
+- `exitCode`: The last exit code of the job.
+- `stdout`: The standard output of the job. This just means the normal logs of the process.
+- `stderr`: The standard error stream of the process. This (usually) includes error messages of the job.
+
+## Functions
+### background()
+Puts a job in the background. This acts the same as initially running a job.
+
+### foreground()
+Puts a job in the foreground. This will cause it to run like it was
+executed normally and wait for it to complete.
+
+### start()
+Starts running the job.
+
+### stop()
+Stops the job from running.
+
+### add(cmdstr, args, execPath)
+Adds a new job to the job table. Note that this does not immediately run it.
+
+### all()
+Returns a table of all job objects.
+
+### disown(id)
+Disowns a job. This deletes it from the job table.
+
+### get(id)
+Get a job object via its ID.
+
+### last() -> Job
+Returns the last added job from the table.
+

docs/api/hilbish/hilbish.os.md

@@ -9,7 +9,8 @@ The `os` interface provides simple text information properties about
 the current OS on the systen. This mainly includes the name and
 version.
 
-## Properties
+## Interface fields
 - `family`: Family name of the current OS
 - `name`: Pretty name of the current OS
 - `version`: Version of the current OS
+

docs/api/hilbish/hilbish.userDir.md

@@ -9,6 +9,7 @@ This interface just contains properties to know about certain user directories.
 It is equivalent to XDG on Linux and gets the user's preferred directories
 for configs and data.
 
-## Properties
+## Interface fields
 - `config`: The user's config directory
 - `data`: The user's directory for program data
+

emmyLuaDocs/hilbish.lua

@@ -128,16 +128,29 @@ function hilbish.timeout(cb, time) end
 --- @param binName string
 function hilbish.which(name) end
 
+--- Puts a job in the background. This acts the same as initially running a job.
+function hilbish.jobs:background() end
+
 --- Returns binary/executale completion candidates based on the provided query.
 function hilbish.completions.bins(query, ctx, fields) end
 
 --- Returns file completion candidates based on the provided query.
 function hilbish.completions.files(query, ctx, fields) end
 
+--- Puts a job in the foreground. This will cause it to run like it was
+--- executed normally and wait for it to complete.
+function hilbish.jobs:foreground() end
+
 --- Evaluates `cmd` as Lua input. This is the same as using `dofile`
 --- or `load`, but is appropriated for the runner interface.
 function hilbish.runner.lua(cmd) end
 
+--- Starts running the job.
+function hilbish.jobs:start() end
+
+--- Stops the job from running.
+function hilbish.jobs.stop() end
+
 --- Runs a command in Hilbish's shell script interpreter.
 --- This is the equivalent of using `source`.
 function hilbish.runner.sh(cmd) end
@@ -156,6 +169,21 @@ function hilbish.aliases.list() end
 --- @param alias string
 function hilbish.aliases.resolve(alias) end
 
+--- Adds a new job to the job table. Note that this does not immediately run it.
+function hilbish.jobs.add(cmdstr, args, execPath) end
+
+--- Returns a table of all job objects.
+function hilbish.jobs.all() end
+
+--- Disowns a job. This deletes it from the job table.
+function hilbish.jobs.disown(id) end
+
+--- Get a job object via its ID.
+function hilbish.jobs.get(id) end
+
+--- Returns the last added job from the table.
+function hilbish.jobs.last() end
+
 --- Adds a command to the history.
 --- @param cmd string
 function hilbish.history.add(cmd) end

job.go

@@ -110,6 +110,10 @@ func (j *job) getProc() *os.Process {
 	return nil
 }
 
+// #interface jobs
+// #member
+// start()
+// Starts running the job.
 func luaStartJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -130,6 +134,9 @@ func luaStartJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
+// #interface jobs
+// stop()
+// Stops the job from running.
 func luaStopJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -148,6 +155,11 @@ func luaStopJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
+// #interface jobs
+// #member
+// foreground()
+// Puts a job in the foreground. This will cause it to run like it was
+// executed normally and wait for it to complete.
 func luaForegroundJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -180,6 +192,10 @@ func luaForegroundJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
+// #interface jobs
+// #member
+// background()
+// Puts a job in the background. This acts the same as initially running a job.
 func luaBackgroundJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -276,6 +292,20 @@ func (j *jobHandler) stopAll() {
 	}
 }
 
+// #interface jobs
+// #property cmd The user entered command string for the job.
+// #property running Whether the job is running or not.
+// #property id The ID of the job in the job table
+// #property pid The Process ID
+// #property exitCode The last exit code of the job.
+// #property stdout The standard output of the job. This just means the normal logs of the process.
+// #property stderr The standard error stream of the process. This (usually) includes error messages of the job.
+// background job management
+/*
+Manage interactive jobs in Hilbish via Lua.
+
+Jobs are the name of background tasks/commands. A job can be started via
+interactive usage or with the functions defined below for use in external runners. */
 func (j *jobHandler) loader(rtm *rt.Runtime) *rt.Table {
 	jobMethods := rt.NewTable()
 	jFuncs := map[string]util.LuaExport{
@@ -353,6 +383,9 @@ func jobUserData(j *job) *rt.UserData {
 	return rt.NewUserData(j, jobMeta.AsTable())
 }
 
+// #interface jobs
+// get(id)
+// Get a job object via its ID.
 func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	j.mu.RLock()
 	defer j.mu.RUnlock()
@@ -373,6 +406,9 @@ func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext(t.Runtime, rt.UserDataValue(job.ud)), nil
 }
 
+// #interface jobs
+// add(cmdstr, args, execPath)
+// Adds a new job to the job table. Note that this does not immediately run it.
 func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(3); err != nil {
 		return nil, err
@@ -402,6 +438,9 @@ func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, rt.UserDataValue(jb.ud)), nil
 }
 
+// #interface jobs
+// all()
+// Returns a table of all job objects.
 func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	j.mu.RLock()
 	defer j.mu.RUnlock()
@@ -414,6 +453,9 @@ func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, rt.TableValue(jobTbl)), nil
 }
 
+// #interface jobs
+// disown(id)
+// Disowns a job. This deletes it from the job table.
 func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -431,6 +473,9 @@ func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
+// #interface jobs
+// last() -> Job
+// Returns the last added job from the table.
 func (j *jobHandler) luaLastJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	j.mu.RLock()
 	defer j.mu.RUnlock()

os.go

@@ -12,9 +12,9 @@ import (
 // The `os` interface provides simple text information properties about
 // the current OS on the systen. This mainly includes the name and
 // version.
-// #property family Family name of the current OS
-// #property name Pretty name of the current OS
-// #property version Version of the current OS
+// #field family Family name of the current OS
+// #field name Pretty name of the current OS
+// #field version Version of the current OS
 func hshosLoader(rtm *rt.Runtime) *rt.Table {
 	info, _ := osinfo.GetOSInfo()
 	mod := rt.NewTable()

userdir.go

@@ -11,8 +11,8 @@ import (
 // This interface just contains properties to know about certain user directories.
 // It is equivalent to XDG on Linux and gets the user's preferred directories
 // for configs and data.
-// #property config The user's config directory
-// #property data The user's directory for program data
+// #field config The user's config directory
+// #field data The user's directory for program data
 func userDirLoader(rtm *rt.Runtime) *rt.Table {
 	mod := rt.NewTable()