docs: add docs for sink type (closes #233)

cmd/docgen/docgen.go

@@ -126,12 +126,12 @@ func docPieceTag(tagName string, tags map[string][]tag) []docPiece {
 
 func setupDocType(mod string, typ *doc.Type) *docPiece {
 	docs := strings.TrimSpace(typ.Doc)
-	inInterface := strings.HasPrefix(docs, "#interface")
+	tags, doc := getTagsAndDocs(docs)
-	if !inInterface {
+
+	if tags["type"] == nil {
 		return nil
 	}
-
+	inInterface := tags["interface"] != nil
-	tags, doc := getTagsAndDocs(docs)
 
 	var interfaces string
 	typeName := strings.ToUpper(string(typ.Name[0])) + typ.Name[1:]
@@ -168,10 +168,7 @@ func setupDocType(mod string, typ *doc.Type) *docPiece {
 	if tags["member"] != nil {
 		isMember = true
 	}
-	var parentMod string
+	parentMod := mod
-	if inInterface {
-		parentMod = mod
-	}
 	dps := &docPiece{
 		Doc: typeDoc,
 		FuncName: typeName,
@@ -191,13 +188,19 @@ func setupDocType(mod string, typ *doc.Type) *docPiece {
 
 func setupDoc(mod string, fun *doc.Func) *docPiece {
 	docs := strings.TrimSpace(fun.Doc)
-	inInterface := strings.HasPrefix(docs, "#interface")
+	tags, parts := getTagsAndDocs(docs)
-	if (!strings.HasPrefix(fun.Name, prefix[mod]) && !inInterface) || (strings.ToLower(fun.Name) == "loader" && !inInterface) {
+
+	// i couldnt fit this into the condition below for some reason so here's a goto!
+	if tags["member"] != nil {
+		goto start
+	}
+
+	if (!strings.HasPrefix(fun.Name, prefix[mod]) && tags["interface"] == nil) || (strings.ToLower(fun.Name) == "loader" && tags["interface"] == nil) {
 		return nil
 	}
 
-	tags, parts := getTagsAndDocs(docs)
+start:
-
+	inInterface := tags["interface"] != nil
 	var interfaces string
 	funcsig := parts[0]
 	doc := parts[1:]
@@ -418,7 +421,11 @@ func main() {
 			modDescription := typeTag.ReplaceAllStringFunc(strings.Replace(modu.Description, "<", `\<`, -1), func(typ string) string {
 				typName := typ[1:]
 				typLookup := typeTable[strings.ToLower(typName)]
-				linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s/#%s", typLookup[0], typLookup[0] + "." + typLookup[1], strings.ToLower(typName))
+				ifaces := typLookup[0] + "." + typLookup[1] + "/"
+				if typLookup[1] == "" {
+					ifaces = ""
+				}
+				linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s#%s", typLookup[0], ifaces, strings.ToLower(typName))
 				return fmt.Sprintf(`<a href="%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName)
 			})
 			f.WriteString(fmt.Sprintf("## Introduction\n%s\n\n", modDescription))
@@ -450,7 +457,11 @@ func main() {
 					htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(dps.FuncSig, "<", `\<`, -1), func(typ string) string {
 						typName := typ[1:]
 						typLookup := typeTable[strings.ToLower(typName)]
-						linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s/#%s", typLookup[0], typLookup[0] + "." + typLookup[1], strings.ToLower(typName))
+						ifaces := typLookup[0] + "." + typLookup[1] + "/"
+						if typLookup[1] == "" {
+							ifaces = ""
+						}
+						linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s#%s", typLookup[0], ifaces, strings.ToLower(typName))
 						return fmt.Sprintf(`<a href="%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName)
 					})
 					f.WriteString(fmt.Sprintf("### %s\n", htmlSig))
@@ -487,10 +498,10 @@ func main() {
 							continue
 						}
 						htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(dps.FuncSig, "<", `\<`, -1), func(typ string) string {
-							// todo: get type from global table to link to
+							typName := regexp.MustCompile(`\w+`).FindString(typ[1:])
-							// other pages (hilbish page can link to hilbish.jobs#Job)
+							typLookup := typeTable[strings.ToLower(typName)]
-							typName := typ[1:]
+							fmt.Printf("%+q, \n", typLookup)
-							linkedTyp := strings.ToLower(typName) // TODO: link
+							linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s/#%s", typLookup[0], typLookup[0] + "." + typLookup[1], strings.ToLower(typName))
 							return fmt.Sprintf(`<a href="#%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName)
 						})
 						f.WriteString(fmt.Sprintf("#### %s\n", htmlSig))

docs/api/commander.md

@@ -27,12 +27,9 @@ In this example, a command with the name of `hello` is created
 that will print `Hello world!` to output. One question you may
 have is: What is the `sinks` parameter?
 
-A sink is a writable/readable pipe, or you can imagine a Lua
+The `sinks` parameter is a table with 3 keys: `in`, `out`,
-file. It's used in this case to write to the proper output,
+and `err`. The values of these is a <a href="/Hilbish/docs/api/hilbish/#sink" style="text-decoration: none;">Sink</a>.
-incase a user either pipes to another command or redirects somewhere else.
 
-So, the `sinks` parameter is a table containing 3 sinks:
-`in`, `out`, and `err`.
 - `in` is the standard input. You can read from this sink
 to get user input. (**This is currently unimplemented.**)
 - `out` is standard output. This is usually where text meant for
@@ -40,10 +37,6 @@ output should go.
 - `err` is standard error. This sink is for writing errors, as the
 name would suggest.
 
-A sink has 2 methods:
-- `write(str)` will write to the sink.
-- `writeln(str)` will write to the sink with a newline at the end.
-
 ## Functions
 ### deregister(name)
 Deregisters any command registered with `name`

docs/api/hilbish/_index.md

@@ -103,3 +103,15 @@ This creates a timer that starts immediately.
 Checks if `name` is a valid command.
 Will return the path of the binary, or a basename if it's a commander.
 
+## Types
+## Sink
+A sink is a structure that has input and/or output to/from
+a desination.
+
+### Methods
+#### write(str)
+Writes data to a sink.
+
+#### writeln(str)
+Writes data to a sink with a newline at the end.
+

emmyLuaDocs/hilbish.lua

@@ -179,6 +179,12 @@ function hilbish.jobs:foreground() end
 --- @param cmd string
 function hilbish.runner.lua(cmd) end
 
+--- Writes data to a sink.
+function hilbish:write(str) end
+
+--- Writes data to a sink with a newline at the end.
+function hilbish:writeln(str) end
+
 --- Starts running the job.
 function hilbish.jobs:start() end
 

golibs/commander/commander.go

@@ -18,22 +18,15 @@ In this example, a command with the name of `hello` is created
 that will print `Hello world!` to output. One question you may
 have is: What is the `sinks` parameter?
 
-A sink is a writable/readable pipe, or you can imagine a Lua
+The `sinks` parameter is a table with 3 keys: `in`, `out`,
-file. It's used in this case to write to the proper output,
+and `err`. The values of these is a @Sink.
-incase a user either pipes to another command or redirects somewhere else.
 
-So, the `sinks` parameter is a table containing 3 sinks:
-`in`, `out`, and `err`.
 - `in` is the standard input. You can read from this sink
 to get user input. (**This is currently unimplemented.**)
 - `out` is standard output. This is usually where text meant for
 output should go.
 - `err` is standard error. This sink is for writing errors, as the
 name would suggest.
-
-A sink has 2 methods:
-- `write(str)` will write to the sink.
-- `writeln(str)` will write to the sink with a newline at the end.
 */
 package commander
 

job.go

@@ -18,6 +18,7 @@ import (
 var jobs *jobHandler
 var jobMetaKey = rt.StringValue("hshjob")
 
+// #type
 // #interface jobs
 // #property cmd The user entered command string for the job.
 // #property running Whether the job is running or not.

sink.go

@@ -11,8 +11,9 @@ import (
 
 var sinkMetaKey = rt.StringValue("hshsink")
 
-// a sink is a structure that has input and/or output
+// #type
-// it is like a lua file when used in popen, but specific to hilbish
+// A sink is a structure that has input and/or output to/from
+// a desination.
 type sink struct{
 	writer io.Writer
 	reader io.Reader
@@ -40,6 +41,9 @@ func setupSinkType(rtm *rt.Runtime) {
 	l.SetRegistry(sinkMetaKey, rt.TableValue(sinkMeta))
 }
 
+// #member
+// write(str)
+// Writes data to a sink.
 func luaSinkWrite(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
 		return nil, err
@@ -59,6 +63,9 @@ func luaSinkWrite(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
+// #member
+// writeln(str)
+// Writes data to a sink with a newline at the end.
 func luaSinkWriteln(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
 		return nil, err

timer.go

@@ -15,6 +15,7 @@ const (
 	timerTimeout
 )
 
+// #type
 // #interface timers
 // #property type What type of timer it is
 // #property running If the timer is running