docs: document job type

cmd/docgen/docgen.go

@@ -7,6 +7,7 @@ import (
 	"go/doc"
 	"go/parser"
 	"go/token"
+	"regexp"
 	"strings"
 	"os"
 	"sync"
@@ -31,6 +32,7 @@ type emmyPiece struct {
 }
 
 type module struct {
+	Types []docPiece
 	Docs []docPiece
 	Fields []docPiece
 	Properties []docPiece
@@ -38,6 +40,7 @@ type module struct {
 	Description string
 	ParentModule string
 	HasInterfaces bool
+	HasTypes bool
 }
 
 type docPiece struct {
@@ -49,6 +52,7 @@ type docPiece struct {
 	GoFuncName string
 	IsInterface bool
 	IsMember bool
+	IsType bool
 	Fields []docPiece
 	Properties []docPiece
 }
@@ -119,6 +123,69 @@ func docPieceTag(tagName string, tags map[string][]tag) []docPiece {
 	return dps
 }
 
+func setupDocType(mod string, typ *doc.Type) *docPiece {
+	docs := strings.TrimSpace(typ.Doc)
+	inInterface := strings.HasPrefix(docs, "#interface")
+	if !inInterface {
+		return nil
+	}
+
+	tags, doc := getTagsAndDocs(docs)
+
+	var interfaces string
+	typeName := strings.ToUpper(string(typ.Name[0])) + typ.Name[1:]
+	typeDoc := []string{}
+
+	if inInterface {
+		interfaces = tags["interface"][0].id
+	}
+
+	fields := docPieceTag("field", tags)
+	properties := docPieceTag("property", tags)
+
+	for _, d := range doc {
+		if strings.HasPrefix(d, "---") {
+			// TODO: document types in lua
+			/*
+			emmyLine := strings.TrimSpace(strings.TrimPrefix(d, "---"))
+			emmyLinePieces := strings.Split(emmyLine, " ")
+			emmyType := emmyLinePieces[0]
+			if emmyType == "@param" {
+				em.Params = append(em.Params, emmyLinePieces[1])
+			}
+			if emmyType == "@vararg" {
+				em.Params = append(em.Params, "...") // add vararg
+			}
+			em.Annotations = append(em.Annotations, d)
+			*/
+		} else {
+			typeDoc = append(typeDoc, d)
+		}
+	}
+
+	var isMember bool
+	if tags["member"] != nil {
+		isMember = true
+	}
+	var parentMod string
+	if inInterface {
+		parentMod = mod
+	}
+	dps := &docPiece{
+		Doc: typeDoc,
+		FuncName: typeName,
+		Interfacing: interfaces,
+		IsInterface: inInterface,
+		IsMember: isMember,
+		IsType: true,
+		ParentModule: parentMod,
+		Fields: fields,
+		Properties: properties,
+	}
+
+	return dps
+}
+
 func setupDoc(mod string, fun *doc.Func) *docPiece {
 	docs := strings.TrimSpace(fun.Doc)
 	inInterface := strings.HasPrefix(docs, "#interface")
@@ -220,6 +287,7 @@ func main() {
 	for l, f := range pkgs {
 		p := doc.New(f, "./", doc.AllDecls)
 		pieces := []docPiece{}
+		typePieces := []docPiece{}
 		mod := l
 		if mod == "main" {
 			mod = "hilbish"
@@ -237,6 +305,14 @@ func main() {
 			}
 		}
 		for _, t := range p.Types {
+			typePiece := setupDocType(mod, t)
+			if typePiece != nil {
+				typePieces = append(typePieces, *typePiece)
+				if typePiece.IsInterface {
+					hasInterfaces = true
+				}
+			}
+
 			for _, m := range t.Methods {
 				piece := setupDoc(mod, m)
 				if piece == nil {
@@ -254,6 +330,7 @@ func main() {
 		shortDesc := descParts[0]
 		desc := descParts[1:]
 		filteredPieces := []docPiece{}
+		filteredTypePieces := []docPiece{}
 		for _, piece := range pieces {
 			if !piece.IsInterface {
 				filteredPieces = append(filteredPieces, piece)
@@ -276,10 +353,28 @@ func main() {
 				interfaceModules[modname].Properties = piece.Properties
 				continue
 			}
+
 			interfaceModules[modname].Docs = append(interfaceModules[modname].Docs, piece)
 		}
 
+		for _, piece := range typePieces {
+			if !piece.IsInterface {
+				filteredTypePieces = append(filteredTypePieces, piece)
+				continue
+			}
+
+			modname := piece.ParentModule + "." + piece.Interfacing
+			if interfaceModules[modname] == nil {
+				interfaceModules[modname] = &module{
+					ParentModule: piece.ParentModule,
+				}
+			}
+
+			interfaceModules[modname].Types = append(interfaceModules[modname].Types, piece)
+		}
+
 		docs[mod] = module{
+			Types: filteredTypePieces,
 			Docs: filteredPieces,
 			ShortDescription: shortDesc,
 			Description: strings.Join(desc, "\n"),
@@ -335,11 +430,39 @@ func main() {
 				}
 				f.WriteString("\n")
 			}
-			if len(modu.Docs) != 0 {
-				f.WriteString("## Functions\n")
+			if len(modu.Types) != 0 {
+				f.WriteString("## Types\n")
+				for _, dps := range modu.Types {
+					f.WriteString(fmt.Sprintf("### %s\n", dps.FuncName))
+					for _, doc := range dps.Doc {
+						if !strings.HasPrefix(doc, "---") {
+							f.WriteString(doc + "\n")
 						}
+					}
+					if len(dps.Properties) != 0 {
+						f.WriteString("#### Properties\n")
+						for _, dps := range dps.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 {
+				typeTag, _ := regexp.Compile(`@\w+`)
+				f.WriteString("## Functions\n")
 				for _, dps := range modu.Docs {
-				f.WriteString(fmt.Sprintf("### %s\n", dps.FuncSig))
+					htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(dps.FuncSig, "<", `\<`, -1), func(typ string) string {
+						// todo: get type from global table to link to
+						// other pages (hilbish page can link to hilbish.jobs#Job)
+						typName := typ[1:]
+						linkedTyp := strings.ToLower(typName) // TODO: link
+						return fmt.Sprintf(`<a href="#%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName)
+					})
+					f.WriteString(fmt.Sprintf("### %s\n", htmlSig))
 					for _, doc := range dps.Doc {
 						if !strings.HasPrefix(doc, "---") {
 							f.WriteString(doc + "\n")
@@ -347,6 +470,7 @@ func main() {
 					}
 					f.WriteString("\n")
 				}
+			}
 		}(mod, docPath, v)
 
 		go func(md, modname string, modu module) {

docs/api/hilbish/hilbish.aliases.md

@@ -17,9 +17,8 @@ This is an alias (ha) for the `hilbish.alias` function.
 ### delete(name)
 Removes an alias.
 
-### list() -> aliases (table)
+### list() -> table\<string, string>
 Get a table of all aliases, with string keys as the alias and the value as the command.
-@returns table<string, string>
 
 ### resolve(alias) -> command (string)
 Tries to resolve an alias to its command.

docs/api/hilbish/hilbish.jobs.md

@@ -14,7 +14,10 @@ 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
+## Types
+### Job
+Job Type.
+#### 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
@@ -40,15 +43,15 @@ 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() -> jobs (table<Job/Table>)
+### all() -> table\<<a href="#job" style="text-decoration: none;">Job</a>>
 Returns a table of all job objects.
 
 ### disown(id)
 Disowns a job. This deletes it from the job table.
 
-### get(id) -> job (Job/Table)
+### get(id) -> <a href="#job" style="text-decoration: none;">Job</a>
 Get a job object via its ID.
 
-### last() -> job (Job/Table)
+### last() -> <a href="#job" style="text-decoration: none;">Job</a>
 Returns the last added job from the table.
 

job.go

@@ -18,6 +18,15 @@ import (
 var jobs *jobHandler
 var jobMetaKey = rt.StringValue("hshjob")
 
+// #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.
+// Job Type.
 type job struct {
 	cmd string
 	running bool
@@ -293,13 +302,6 @@ 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.
@@ -384,7 +386,7 @@ func jobUserData(j *job) *rt.UserData {
 }
 
 // #interface jobs
-// get(id) -> job (Job/Table)
+// get(id) -> @Job
 // Get a job object via its ID.
 // --- @param id number
 // --- @returns Job
@@ -444,7 +446,7 @@ func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface jobs
-// all() -> jobs (table<Job/Table>)
+// all() -> table<@Job>
 // Returns a table of all job objects.
 // --- @returns table<Job>
 func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
@@ -481,7 +483,7 @@ func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface jobs
-// last() -> job (Job/Table)
+// last() -> @Job
 // Returns the last added job from the table.
 // --- @returns Job
 func (j *jobHandler) luaLastJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {

website/themes/hsh/layouts/_default/_markup/render-heading.html

@@ -1,6 +1,11 @@
-<h{{ (add .Level 1) }} id="{{ .Anchor | safeURL }}">
+
+<h{{ (add .Level 1) }} id="{{ .Anchor | safeURL }}" class="heading">
 	{{ .Text | safeHTML }}
+	<a href="#{{ .Anchor | safeURL }}" class='heading-link'>
+		<i class="fas fa-paperclip"></i>
+	</a>
 </h{{ (add .Level 1) }}>
+
 {{ if eq .Text ""}}
 	<hr>
 {{ end }}

website/themes/hsh/layouts/partials/head.html

@@ -23,4 +23,16 @@
 	<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-0evHe/X+R7YkIZDRvuzKMRqM+OrBnVFBL6DOitfPri4tjfHxaWutUpFmBp4vmVor" crossorigin="anonymous">
 	<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/js/bootstrap.bundle.min.js" integrity="sha384-pprn3073KE6tl6bjs2QrFaJGz5/SUsLqktiwsUTF55Jfv3qYSDhgCecCxMW52nD2" crossorigin="anonymous"></script>
 	<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css" integrity="sha512-KfkfwYDsLkIlwQp6LFnl8zNdLGxu9YAA1QvwINks4PhcElQSvqcyVLLD9aMhXd13uQjoXtEKNosOWaZqXgel0g==" crossorigin="anonymous" referrerpolicy="no-referrer" />
+
+	<style>
+	.heading > .heading-link {
+		opacity: 0
+	}
+
+	.heading:hover > .heading-link {
+		visibility: visible;
+		opacity: 1;
+		transition: all .1s ease-in;
+	}
+	</style>
 </head>