From 2363e6ff2f2b33a3b3b8584f221c007f4229eff3 Mon Sep 17 00:00:00 2001 From: sammyette Date: Thu, 30 Nov 2023 18:30:54 -0400 Subject: [PATCH] website(docs): add example --- cmd/docgen/docgen.go | 21 +++++++++++++++++++-- docs/api/bait.md | 16 ++++++++++++---- docs/hooks/_index.md | 15 ++------------- emmyLuaDocs/bait.lua | 4 +++- golibs/bait/bait.go | 13 ++++++++++--- 5 files changed, 46 insertions(+), 23 deletions(-) diff --git a/cmd/docgen/docgen.go b/cmd/docgen/docgen.go index 5b452d7..6e295be 100644 --- a/cmd/docgen/docgen.go +++ b/cmd/docgen/docgen.go @@ -64,11 +64,13 @@ type docPiece struct { Fields []docPiece Properties []docPiece Params []param + Tags map[string][]tag } type tag struct { id string fields []string + startIdx int } var docs = make(map[string]module) @@ -89,7 +91,7 @@ func getTagsAndDocs(docs string) (map[string][]tag, []string) { parts := []string{} tags := make(map[string][]tag) - for _, part := range pts { + for idx, part := range pts { if strings.HasPrefix(part, "#") { tagParts := strings.Split(strings.TrimPrefix(part, "#"), " ") if tags[tagParts[0]] == nil { @@ -98,12 +100,21 @@ func getTagsAndDocs(docs string) (map[string][]tag, []string) { id = tagParts[1] } tags[tagParts[0]] = []tag{ - {id: id}, + {id: id, startIdx: idx}, } if len(tagParts) >= 2 { tags[tagParts[0]][0].fields = tagParts[2:] } } else { + if tagParts[0] == "example" { + exampleIdx := tags["example"][0].startIdx + exampleCode := pts[exampleIdx+1:idx] + + tags["example"][0].fields = exampleCode + parts = strings.Split(strings.Replace(strings.Join(parts, "\n"), strings.TrimPrefix(strings.Join(exampleCode, "\n"), "#example\n"), "", -1), "\n") + continue + } + fleds := []string{} if len(tagParts) >= 2 { fleds = tagParts[2:] @@ -188,6 +199,7 @@ func setupDocType(mod string, typ *doc.Type) *docPiece { ParentModule: parentMod, Fields: fields, Properties: properties, + Tags: tags, } typeTable[strings.ToLower(typeName)] = []string{parentMod, interfaces} @@ -273,6 +285,7 @@ start: Fields: fields, Properties: properties, Params: params, + Tags: tags, } if strings.HasSuffix(dps.GoFuncName, strings.ToLower("loader")) { dps.Doc = parts @@ -565,6 +578,10 @@ func main() { f.WriteString(strings.Join(p.Doc, " ")) f.WriteString("\n\n") } + if codeExample := dps.Tags["example"]; codeExample != nil { + f.WriteString("#### Example\n") + f.WriteString(fmt.Sprintf("```lua\n%s\n````\n", strings.Join(codeExample[0].fields, "\n"))) + } f.WriteString("") f.WriteString("\n\n") } diff --git a/docs/api/bait.md b/docs/api/bait.md index 91cfb31..cc0eb1a 100644 --- a/docs/api/bait.md +++ b/docs/api/bait.md @@ -35,7 +35,7 @@ this function will set the user prompt. ## Functions ||| |----|----| -|catch(name, cb)|Catches a hook with `name`. Runs the `cb` when it is thrown| +|catch(name, cb)|Catches a hook. This function is used to act on hooks/events.| |catchOnce(name, cb)|Same as catch, but only runs the `cb` once and then removes the hook| |hooks(name) -> table|Returns a table with hooks (callback functions) on the event with `name`.| |release(name, catcher)|Removes the `catcher` for the event with `name`.| @@ -49,14 +49,22 @@ bait.catch(name, cb) -Catches a hook with `name`. Runs the `cb` when it is thrown +Catches a hook. This function is used to act on hooks/events. + + #### Parameters `string` **`name`** -ummm +The name of the hook. `function` **`cb`** -? +The function that will be called when the hook is thrown. +#### Example +```lua +bait.catch('hilbish.exit', function() + print 'Goodbye Hilbish!' +end) +````
diff --git a/docs/hooks/_index.md b/docs/hooks/_index.md index 500b6e6..bb23477 100644 --- a/docs/hooks/_index.md +++ b/docs/hooks/_index.md @@ -7,16 +7,5 @@ menu: docs --- -Here is a list of bait hooks that are thrown by Hilbish. If a hook is related -to a command, it will have the `command` scope, as example. - -Here is the format for a doc for a hook: -+ {hook name} -> args > description - -`{args}` just means the arguments of the hook. If a hook doc has the format -of `arg...`, it means the hook can take/recieve any number of `arg`. - -+ error -> eventName, handler, err > Emitted when there is an error in -an event handler. The `eventName` is the name of the event the handler -is for, the `handler` is the callback function, and `err` is the error -message. +Hooks are Hilbish's versions of events, which are used via the [Bait](../api/bait) module. +For more detail on how to act on these hooks, you may check the Bait page. diff --git a/emmyLuaDocs/bait.lua b/emmyLuaDocs/bait.lua index 6ca76ab..4b74f82 100644 --- a/emmyLuaDocs/bait.lua +++ b/emmyLuaDocs/bait.lua @@ -2,7 +2,9 @@ local bait = {} ---- Catches a hook with `name`. Runs the `cb` when it is thrown +--- Catches a hook. This function is used to act on hooks/events. +--- +--- function bait.catch(name, cb) end --- Same as catch, but only runs the `cb` once and then removes the hook diff --git a/golibs/bait/bait.go b/golibs/bait/bait.go index dca3773..e0a29da 100644 --- a/golibs/bait/bait.go +++ b/golibs/bait/bait.go @@ -271,9 +271,16 @@ func (b *Bait) bthrow(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { } // catch(name, cb) -// Catches a hook with `name`. Runs the `cb` when it is thrown -// #param name string ummm -// #param cb function ? +// Catches a hook. This function is used to act on hooks/events. +// #param name string The name of the hook. +// #param cb function The function that will be called when the hook is thrown. +/* +#example +bait.catch('hilbish.exit', function() + print 'Goodbye Hilbish!' +end) +#example +*/ func (b *Bait) bcatch(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { name, catcher, err := util.HandleStrCallback(t, c) if err != nil {