From 0f97abef0fb42a55654065d50878a34ce1486107 Mon Sep 17 00:00:00 2001
From: sammyette <torchedsammy@gmail.com>
Date: Wed, 14 Dec 2022 23:54:10 -0400
Subject: [PATCH] docs: support field docs for modules

---
 api.go                     |  8 ++++++
 cmd/docgen/docgen.go       | 55 +++++++++++++++++++++-----------------
 docs/api/hilbish/_index.md | 10 +++++++
 3 files changed, 49 insertions(+), 24 deletions(-)

diff --git a/api.go b/api.go
index 787da24..09df7c0 100644
--- a/api.go
+++ b/api.go
@@ -1,6 +1,14 @@
 // the core Hilbish API
 // The Hilbish module includes the core API, containing
 // interfaces and functions which directly relate to shell functionality.
+// #field ver The version of Hilbish
+// #field user Username of the user
+// #field host Hostname of the machine
+// #field dataDir Directory for Hilbish data files, including the docs and default modules
+// #field interactive Is Hilbish in an interactive shell?
+// #field login Is Hilbish the login shell?
+// #field vimMode Current Vim input mode of Hilbish (will be nil if not in Vim input mode)
+// #field exitCode xit code of the last executed command
 package main
 
 import (
diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go
index 4072023..cf70840 100644
--- a/cmd/docgen/docgen.go
+++ b/cmd/docgen/docgen.go
@@ -70,16 +70,11 @@ var prefix = map[string]string{
 	"terminal": "term",
 }
 
-func setupDoc(mod string, fun *doc.Func) *docPiece {
-	docs := strings.TrimSpace(fun.Doc)
-	inInterface := strings.HasPrefix(docs, "#interface")
-	if (!strings.HasPrefix(fun.Name, prefix[mod]) && !inInterface) || (strings.ToLower(fun.Name) == "loader" && !inInterface) {
-		return nil
-	}
-
+func getTagsAndDocs(docs string) (map[string][]tag, []string) {
 	pts := strings.Split(docs, "\n")
 	parts := []string{}
 	tags := make(map[string][]tag)
+
 	for _, part := range pts {
 		if strings.HasPrefix(part, "#") {
 			tagParts := strings.Split(strings.TrimPrefix(part, "#"), " ")
@@ -109,6 +104,30 @@ func setupDoc(mod string, fun *doc.Func) *docPiece {
 		}
 	}
 
+	return tags, parts
+}
+
+func docPieceTag(tagName string, tags map[string][]tag) []docPiece {
+	dps := []docPiece{}
+	for _, tag := range tags[tagName] {
+		dps = append(dps, docPiece{
+			FuncName: tag.id,
+			Doc: tag.fields,
+		})
+	}
+
+	return dps
+}
+
+func setupDoc(mod string, fun *doc.Func) *docPiece {
+	docs := strings.TrimSpace(fun.Doc)
+	inInterface := strings.HasPrefix(docs, "#interface")
+	if (!strings.HasPrefix(fun.Name, prefix[mod]) && !inInterface) || (strings.ToLower(fun.Name) == "loader" && !inInterface) {
+		return nil
+	}
+
+	tags, parts := getTagsAndDocs(docs)
+
 	var interfaces string
 	funcsig := parts[0]
 	doc := parts[1:]
@@ -121,22 +140,8 @@ func setupDoc(mod string, fun *doc.Func) *docPiece {
 	}
 	em := emmyPiece{FuncName: funcName}
 
-	// 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{
-			FuncName: tag.id,
-			Doc: tag.fields,
-		})
-	}
+	fields := docPieceTag("field", tags)
+	properties := docPieceTag("property", tags)
 
 	for _, d := range doc {
 		if strings.HasPrefix(d, "---") {
@@ -245,7 +250,7 @@ func main() {
 			}
 		}
 
-		descParts := strings.Split(strings.TrimSpace(p.Doc), "\n")
+		tags, descParts := getTagsAndDocs(strings.TrimSpace(p.Doc))
 		shortDesc := descParts[0]
 		desc := descParts[1:]
 		filteredPieces := []docPiece{}
@@ -279,6 +284,8 @@ func main() {
 			ShortDescription: shortDesc,
 			Description: strings.Join(desc, "\n"),
 			HasInterfaces: hasInterfaces,
+			Properties: docPieceTag("property", tags),
+			Fields: docPieceTag("field", tags),
 		}
 	}
 
diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md
index ae11539..5cdcb4d 100644
--- a/docs/api/hilbish/_index.md
+++ b/docs/api/hilbish/_index.md
@@ -11,6 +11,16 @@ menu:
 The Hilbish module includes the core API, containing
 interfaces and functions which directly relate to shell functionality.
 
+## Interface fields
+- `ver`: The version of Hilbish
+- `user`: Username of the user
+- `host`: Hostname of the machine
+- `dataDir`: Directory for Hilbish data files, including the docs and default modules
+- `interactive`: Is Hilbish in an interactive shell?
+- `login`: Is Hilbish the login shell?
+- `vimMode`: Current Vim input mode of Hilbish (will be nil if not in Vim input mode)
+- `exitCode`: xit code of the last executed command
+
 ## Functions
 ### alias(cmd, orig)
 Sets an alias of `cmd` to `orig`