From 61914f8dc73d64e6e3b7d88d3a18b7dde43edb49 Mon Sep 17 00:00:00 2001 From: sammyette Date: Tue, 7 Feb 2023 15:39:22 -0400 Subject: [PATCH] docs: add docs for sink type (closes #233) --- cmd/docgen/docgen.go | 47 +++++++++++++++++++++-------------- docs/api/commander.md | 11 ++------ docs/api/hilbish/_index.md | 12 +++++++++ emmyLuaDocs/hilbish.lua | 6 +++++ golibs/commander/commander.go | 11 ++------ job.go | 1 + sink.go | 11 ++++++-- timer.go | 1 + 8 files changed, 62 insertions(+), 38 deletions(-) diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index c176676..aae6202 100644 --- a/cmd/docgen/docgen.go +++ b/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") - if !inInterface { + tags, doc := getTagsAndDocs(docs) + + if tags["type"] == nil { return nil } - - tags, doc := getTagsAndDocs(docs) + inInterface := tags["interface"] != nil 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 - if inInterface { - parentMod = mod - } + 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") - if (!strings.HasPrefix(fun.Name, prefix[mod]) && !inInterface) || (strings.ToLower(fun.Name) == "loader" && !inInterface) { + tags, parts := getTagsAndDocs(docs) + + // 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(`%s`, 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(`%s`, 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 - // other pages (hilbish page can link to hilbish.jobs#Job) - typName := typ[1:] - linkedTyp := strings.ToLower(typName) // TODO: link + typName := regexp.MustCompile(`\w+`).FindString(typ[1:]) + typLookup := typeTable[strings.ToLower(typName)] + fmt.Printf("%+q, \n", typLookup) + linkedTyp := fmt.Sprintf("/Hilbish/docs/api/%s/%s/#%s", typLookup[0], typLookup[0] + "." + typLookup[1], strings.ToLower(typName)) return fmt.Sprintf(`%s`, linkedTyp, typName) }) f.WriteString(fmt.Sprintf("#### %s\n", htmlSig)) diff --git a/docs/api/commander.md b/docs/api/commander.md index a23dcb1..341eeda 100644 --- a/docs/api/commander.md +++ b/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 -file. It's used in this case to write to the proper output, -incase a user either pipes to another command or redirects somewhere else. +The `sinks` parameter is a table with 3 keys: `in`, `out`, +and `err`. The values of these is a Sink. -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` diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 52bd404..81ca993 100644 --- a/docs/api/hilbish/_index.md +++ b/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. + diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua index 24588bd..d50c58b 100644 --- a/emmyLuaDocs/hilbish.lua +++ b/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 diff --git a/golibs/commander/commander.go b/golibs/commander/commander.go index f67e9b8..c639cf9 100644 --- a/golibs/commander/commander.go +++ b/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 -file. It's used in this case to write to the proper output, -incase a user either pipes to another command or redirects somewhere else. +The `sinks` parameter is a table with 3 keys: `in`, `out`, +and `err`. The values of these is a @Sink. -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 diff --git a/job.go b/job.go index a933016..1beba9c 100644 --- a/job.go +++ b/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. diff --git a/sink.go b/sink.go index 54f5014..9a98856 100644 --- a/sink.go +++ b/sink.go @@ -11,8 +11,9 @@ import ( var sinkMetaKey = rt.StringValue("hshsink") -// a sink is a structure that has input and/or output -// it is like a lua file when used in popen, but specific to hilbish +// #type +// 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 diff --git a/timer.go b/timer.go index d2568b1..5d536f5 100644 --- a/timer.go +++ b/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