website(docs): add example

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("</div>")
 					f.WriteString("\n\n")
 				}

docs/api/bait.md

@@ -35,7 +35,7 @@ this function will set the user prompt.
 ## Functions
 |||
 |----|----|
-|<a href="#catch">catch(name, cb)</a>|Catches a hook with `name`. Runs the `cb` when it is thrown|
+|<a href="#catch">catch(name, cb)</a>|Catches a hook. This function is used to act on hooks/events.|
 |<a href="#catchOnce">catchOnce(name, cb)</a>|Same as catch, but only runs the `cb` once and then removes the hook|
 |<a href="#hooks">hooks(name) -> table</a>|Returns a table with hooks (callback functions) on the event with `name`.|
 |<a href="#release">release(name, catcher)</a>|Removes the `catcher` for the event with `name`.|
@@ -49,14 +49,22 @@ bait.catch(name, cb)
 </a>
 </h4>
 
-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)
+````
 </div>
 
 <hr><div id='catchOnce'>

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.

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

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 {