Merge 5be470521f into 29e14c1aee

cmd/docgen/docgen.go

@@ -64,13 +64,11 @@ 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)
@@ -91,7 +89,7 @@ func getTagsAndDocs(docs string) (map[string][]tag, []string) {
 	parts := []string{}
 	tags := make(map[string][]tag)
 
-	for idx, part := range pts {
+	for _, part := range pts {
 		if strings.HasPrefix(part, "#") {
 			tagParts := strings.Split(strings.TrimPrefix(part, "#"), " ")
 			if tags[tagParts[0]] == nil {
@@ -100,21 +98,12 @@ func getTagsAndDocs(docs string) (map[string][]tag, []string) {
 					id = tagParts[1]
 				}
 				tags[tagParts[0]] = []tag{
-					{id: id, startIdx: idx},
+					{id: id},
 				}
 				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:]
@@ -199,7 +188,6 @@ func setupDocType(mod string, typ *doc.Type) *docPiece {
 		ParentModule: parentMod,
 		Fields: fields,
 		Properties: properties,
-		Tags: tags,
 	}
 
 	typeTable[strings.ToLower(typeName)] = []string{parentMod, interfaces}
@@ -285,7 +273,6 @@ start:
 		Fields: fields,
 		Properties: properties,
 		Params: params,
-		Tags: tags,
 	}
 	if strings.HasSuffix(dps.GoFuncName, strings.ToLower("loader")) {
 		dps.Doc = parts
@@ -578,10 +565,6 @@ 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,11 +35,11 @@ this function will set the user prompt.
 ## Functions
 |||
 |----|----|
-|<a href="#catch">catch(name, cb)</a>|Catches an event. This function can be used to act on events.|
+|<a href="#catch">catch(name, cb)</a>|Catches a hook with `name`. Runs the `cb` when it is thrown|
-|<a href="#catchOnce">catchOnce(name, cb)</a>|Catches an event, but only once. This will remove the hook immediately after it runs for the first time.|
+|<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 list of callbacks that are hooked on an event with the corresponding `name`.|
+|<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`.|
-|<a href="#throw">throw(name, ...args)</a>|Throws a hook with `name` with the provided `args`.|
+|<a href="#throw">throw(name, ...args)</a>|Throws a hook with `name` with the provided `args`|
 
 <hr><div id='catch'>
 <h4 class='heading'>
@@ -49,22 +49,14 @@ bait.catch(name, cb)
 </a>
 </h4>
 
-Catches an event. This function can be used to act on events.
+Catches a hook with `name`. Runs the `cb` when it is thrown
-
-
 #### Parameters
 `string` **`name`**  
-The name of the hook.
+ummm
 
 `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'>
@@ -75,14 +67,9 @@ bait.catchOnce(name, cb)
 </a>
 </h4>
 
-Catches an event, but only once. This will remove the hook immediately after it runs for the first time.
+Same as catch, but only runs the `cb` once and then removes the hook
 #### Parameters
-`string` **`name`**  
+This function has no parameters.  
-The name of the event
-
-`function` **`cb`**  
-The function that will be called when the event is thrown.
-
 </div>
 
 <hr><div id='hooks'>
@@ -93,11 +80,9 @@ bait.hooks(name) -> table
 </a>
 </h4>
 
-Returns a list of callbacks that are hooked on an event with the corresponding `name`.
+Returns a table with hooks (callback functions) on the event with `name`.
 #### Parameters
-`string` **`name`**  
+This function has no parameters.  
-The name of the function
-
 </div>
 
 <hr><div id='release'>
@@ -111,25 +96,8 @@ bait.release(name, catcher)
 Removes the `catcher` for the event with `name`.
 For this to work, `catcher` has to be the same function used to catch
 an event, like one saved to a variable.
-
-
 #### Parameters
-`string` **`name`**  
+This function has no parameters.  
-Name of the event the hook is on
-
-`function` **`catcher`**  
-Hook function to remove
-
-#### Example
-```lua
-local hookCallback = function() print 'hi' end
-
-bait.catch('event', hookCallback)
-
--- a little while later....
-bait.release('event', hookCallback)
--- and now hookCallback will no longer be ran for the event.
-````
 </div>
 
 <hr><div id='throw'>
@@ -140,9 +108,7 @@ bait.throw(name, ...args)
 </a>
 </h4>
 
-Throws a hook with `name` with the provided `args`.
+Throws a hook with `name` with the provided `args`
-
-
 #### Parameters
 `string` **`name`**  
 The name of the hook.
@@ -150,14 +116,5 @@ The name of the hook.
 `any` **`args`** (This type is variadic. You can pass an infinite amount of parameters with this type.)  
 The arguments to pass to the hook.
 
-#### Example
-```lua
-bait.throw('greeting', 'world')
-
--- This can then be listened to via
-bait.catch('gretting', function(greetTo)
-	print('Hello ' .. greetTo)
-end)
-````
 </div>
 

docs/api/commander.md

@@ -9,10 +9,11 @@ menu:
 
 ## Introduction
 
-Commander is the library which handles Hilbish commands. This makes
+Commander is a library for writing custom commands in Lua.
-the user able to add Lua-written commands to their shell without making
+In order to make it easier to write commands for Hilbish,
-a separate script in a bin folder. Instead, you may simply use the Commander
+not require separate scripts and to be able to use in a config,
-library in your Hilbish config.
+the Commander library exists. This is like a very simple wrapper
+that works with Hilbish for writing commands. Example:
 
 ```lua
 local commander = require 'commander'
@@ -27,20 +28,20 @@ that will print `Hello world!` to output. One question you may
 have is: What is the `sinks` parameter?
 
 The `sinks` parameter is a table with 3 keys: `in`, `out`,
-and `err`. All of them are a <a href="/Hilbish/docs/api/hilbish/#sink" style="text-decoration: none;">Sink</a>.
+and `err`. The values of these is a <a href="/Hilbish/docs/api/hilbish/#sink" style="text-decoration: none;">Sink</a>.
 
-- `in` is the standard input.
+- `in` is the standard input. You can read from this sink
-You may use the read functions on this sink to get input from the user.
+to get user input.
-- `out` is standard output.
+- `out` is standard output. This is usually where text meant for
-This is usually where command output should go.
+output should go.
-- `err` is standard error.
+- `err` is standard error. This sink is for writing errors, as the
-This sink is for writing errors, as the name would suggest.
+name would suggest.
 
 ## Functions
 |||
 |----|----|
-|<a href="#deregister">deregister(name)</a>|Removes the named command. Note that this will only remove Commander-registered commands.|
+|<a href="#deregister">deregister(name)</a>|Deregisters any command registered with `name`|
-|<a href="#register">register(name, cb)</a>|Adds a new command with the given `name`. When Hilbish has to run a command with a name,|
+|<a href="#register">register(name, cb)</a>|Register a command with `name` that runs `cb` when ran|
 
 <hr><div id='deregister'>
 <h4 class='heading'>
@@ -50,11 +51,9 @@ commander.deregister(name)
 </a>
 </h4>
 
-Removes the named command. Note that this will only remove Commander-registered commands.
+Deregisters any command registered with `name`
 #### Parameters
-`string` **`name`**  
+This function has no parameters.  
-Name of the command to remove.
-
 </div>
 
 <hr><div id='register'>
@@ -65,27 +64,8 @@ commander.register(name, cb)
 </a>
 </h4>
 
-Adds a new command with the given `name`. When Hilbish has to run a command with a name,
+Register a command with `name` that runs `cb` when ran
-it will run the function providing the arguments and sinks.
-
-
 #### Parameters
-`string` **`name`**  
+This function has no parameters.  
-Name of the command
-
-`function` **`cb`**  
-Callback to handle command invocation
-
-#### Example
-```lua
--- When you run the command `hello` in the shell, it will print `Hello world`.
--- If you run it with, for example, `hello Hilbish`, it will print 'Hello Hilbish'
-commander.register('hello', function(args, sinks)
-	local name = 'world'
-	if #args > 0 then name = args[1] end
-
-	sinks.out:writeln('Hello ' .. name)
-end)
-````
 </div>
 

docs/hooks/_index.md

@@ -7,5 +7,16 @@ menu:
   docs
 ---
 
-Hooks are Hilbish's versions of events, which are used via the [Bait](../api/bait) module.
+Here is a list of bait hooks that are thrown by Hilbish. If a hook is related
-For more detail on how to act on these hooks, you may check the Bait page.
+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.

emmyLuaDocs/bait.lua

@@ -2,27 +2,29 @@
 
 local bait = {}
 
---- Catches an event. This function can be used to act on events.
+--- Catches a hook with `name`. Runs the `cb` when it is thrown
---- 
---- 
 function bait.catch(name, cb) end
 
---- Catches an event, but only once. This will remove the hook immediately after it runs for the first time.
+--- Same as catch, but only runs the `cb` once and then removes the hook
+--- @param name string
+--- @param cb function
 function bait.catchOnce(name, cb) end
 
---- Returns a list of callbacks that are hooked on an event with the corresponding `name`.
+--- Returns a table with hooks (callback functions) on the event with `name`.
+--- @param name string
+--- @returns table<function>
 function bait.hooks(name) end
 
 --- Removes the `catcher` for the event with `name`.
 --- For this to work, `catcher` has to be the same function used to catch
 --- an event, like one saved to a variable.
---- 
+--- @param name string
---- 
+--- @param catcher function
 function bait.release(name, catcher) end
 
---- Throws a hook with `name` with the provided `args`.
+--- Throws a hook with `name` with the provided `args`
---- 
+--- @param name string
---- 
+--- @vararg any
 function bait.throw(name, ...args) end
 
 return bait

emmyLuaDocs/commander.lua

@@ -2,13 +2,13 @@
 
 local commander = {}
 
---- Removes the named command. Note that this will only remove Commander-registered commands.
+--- Deregisters any command registered with `name`
+--- @param name string
 function commander.deregister(name) end
 
---- Adds a new command with the given `name`. When Hilbish has to run a command with a name,
+--- Register a command with `name` that runs `cb` when ran
---- it will run the function providing the arguments and sinks.
+--- @param name string
---- 
+--- @param cb function
---- 
 function commander.register(name, cb) end
 
 return commander

golibs/bait/bait.go

@@ -247,17 +247,33 @@ func handleHook(t *rt.Thread, c *rt.GoCont, name string, catcher *rt.Closure, ar
 	}
 }
 
-// catch(name, cb)
+// throw(name, ...args)
-// Catches an event. This function can be used to act on events.
 // #param name string The name of the hook.
-// #param cb function The function that will be called when the hook is thrown.
+// #param args ...any The arguments to pass to the hook.
-/*
+// Throws a hook with `name` with the provided `args`
-#example
+// --- @param name string
-bait.catch('hilbish.exit', function()
+// --- @vararg any
-	print 'Goodbye Hilbish!'
+func (b *Bait) bthrow(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
-end)
+	if err := c.Check1Arg(); err != nil {
-#example
+		return nil, err
-*/
+	}
+	name, err := c.StringArg(0)
+	if err != nil {
+		return nil, err
+	}
+	ifaceSlice := make([]interface{}, len(c.Etc()))
+	for i, v := range c.Etc() {
+		ifaceSlice[i] = v
+	}
+	b.Emit(name, ifaceSlice...)
+
+	return c.Next(), nil
+}
+
+// catch(name, cb)
+// Catches a hook with `name`. Runs the `cb` when it is thrown
+// #param name string ummm
+// #param cb function ?
 func (b *Bait) bcatch(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	name, catcher, err := util.HandleStrCallback(t, c)
 	if err != nil {
@@ -270,9 +286,9 @@ func (b *Bait) bcatch(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // catchOnce(name, cb)
-// Catches an event, but only once. This will remove the hook immediately after it runs for the first time.
+// Same as catch, but only runs the `cb` once and then removes the hook
-// #param name string The name of the event
+// --- @param name string
-// #param cb function The function that will be called when the event is thrown.
+// --- @param cb function
 func (b *Bait) bcatchOnce(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	name, catcher, err := util.HandleStrCallback(t, c)
 	if err != nil {
@@ -284,10 +300,27 @@ func (b *Bait) bcatchOnce(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
+// release(name, catcher)
+// Removes the `catcher` for the event with `name`.
+// For this to work, `catcher` has to be the same function used to catch
+// an event, like one saved to a variable.
+// --- @param name string
+// --- @param catcher function
+func (b *Bait) brelease(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
+	name, catcher, err := util.HandleStrCallback(t, c)
+	if err != nil {
+		return nil, err
+	}
+
+	b.OffLua(name, catcher)
+
+	return c.Next(), nil
+}
+
 // hooks(name) -> table
-// Returns a list of callbacks that are hooked on an event with the corresponding `name`.
+// Returns a table with hooks (callback functions) on the event with `name`.
-// #param name string The name of the function
+// --- @param name string
-// #returns table<function>
+// --- @returns table<function>
 func (b *Bait) bhooks(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -315,62 +348,3 @@ func (b *Bait) bhooks(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 	return c.PushingNext1(t.Runtime, rt.TableValue(luaHandlers)), nil
 }
-
-// release(name, catcher)
-// Removes the `catcher` for the event with `name`.
-// For this to work, `catcher` has to be the same function used to catch
-// an event, like one saved to a variable.
-// #param name string Name of the event the hook is on
-// #param catcher function Hook function to remove
-/*
-#example
-local hookCallback = function() print 'hi' end
-
-bait.catch('event', hookCallback)
-
--- a little while later....
-bait.release('event', hookCallback)
--- and now hookCallback will no longer be ran for the event.
-#example
-*/
-func (b *Bait) brelease(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
-	name, catcher, err := util.HandleStrCallback(t, c)
-	if err != nil {
-		return nil, err
-	}
-
-	b.OffLua(name, catcher)
-
-	return c.Next(), nil
-}
-
-// throw(name, ...args)
-// #param name string The name of the hook.
-// #param args ...any The arguments to pass to the hook.
-// Throws a hook with `name` with the provided `args`.
-/*
-#example
-bait.throw('greeting', 'world')
-
--- This can then be listened to via
-bait.catch('gretting', function(greetTo)
-	print('Hello ' .. greetTo)
-end)
-#example
-*/
-func (b *Bait) bthrow(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
-	if err := c.Check1Arg(); err != nil {
-		return nil, err
-	}
-	name, err := c.StringArg(0)
-	if err != nil {
-		return nil, err
-	}
-	ifaceSlice := make([]interface{}, len(c.Etc()))
-	for i, v := range c.Etc() {
-		ifaceSlice[i] = v
-	}
-	b.Emit(name, ifaceSlice...)
-
-	return c.Next(), nil
-}

golibs/commander/commander.go

@@ -1,9 +1,10 @@
 // library for custom commands
 /*
-Commander is the library which handles Hilbish commands. This makes
+Commander is a library for writing custom commands in Lua.
-the user able to add Lua-written commands to their shell without making
+In order to make it easier to write commands for Hilbish,
-a separate script in a bin folder. Instead, you may simply use the Commander
+not require separate scripts and to be able to use in a config,
-library in your Hilbish config.
+the Commander library exists. This is like a very simple wrapper
+that works with Hilbish for writing commands. Example:
 
 ```lua
 local commander = require 'commander'
@@ -18,14 +19,14 @@ that will print `Hello world!` to output. One question you may
 have is: What is the `sinks` parameter?
 
 The `sinks` parameter is a table with 3 keys: `in`, `out`,
-and `err`. All of them are a @Sink.
+and `err`. The values of these is a @Sink.
 
-- `in` is the standard input.
+- `in` is the standard input. You can read from this sink
-You may use the read functions on this sink to get input from the user.
+to get user input.
-- `out` is standard output.
+- `out` is standard output. This is usually where text meant for
-This is usually where command output should go.
+output should go.
-- `err` is standard error.
+- `err` is standard error. This sink is for writing errors, as the
-This sink is for writing errors, as the name would suggest.
+name would suggest.
 */
 package commander
 
@@ -66,22 +67,9 @@ func (c *Commander) loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
 }
 
 // register(name, cb)
-// Adds a new command with the given `name`. When Hilbish has to run a command with a name,
+// Register a command with `name` that runs `cb` when ran
-// it will run the function providing the arguments and sinks.
+// --- @param name string
-// #param name string Name of the command
+// --- @param cb function
-// #param cb function Callback to handle command invocation
-/*
-#example
--- When you run the command `hello` in the shell, it will print `Hello world`.
--- If you run it with, for example, `hello Hilbish`, it will print 'Hello Hilbish'
-commander.register('hello', function(args, sinks)
-	local name = 'world'
-	if #args > 0 then name = args[1] end
-
-	sinks.out:writeln('Hello ' .. name)
-end)
-#example
-*/
 func (c *Commander) cregister(t *rt.Thread, ct *rt.GoCont) (rt.Cont, error) {
 	cmdName, cmd, err := util.HandleStrCallback(t, ct)
 	if err != nil {
@@ -94,8 +82,8 @@ func (c *Commander) cregister(t *rt.Thread, ct *rt.GoCont) (rt.Cont, error) {
 }
 
 // deregister(name)
-// Removes the named command. Note that this will only remove Commander-registered commands.
+// Deregisters any command registered with `name`
-// #param name string Name of the command to remove.
+// --- @param name string
 func (c *Commander) cderegister(t *rt.Thread, ct *rt.GoCont) (rt.Cont, error) {
 	if err := ct.Check1Arg(); err != nil {
 		return nil, err

website/config.toml

@@ -30,10 +30,7 @@ enableGitInfo = true
 unsafe = true
 
 [markup.highlight]
-lineNos = true
+style = 'pastie'
-lineNumbersInTable = false
-noClasses = false
-codeFences = true
 
 [author]
 	[author.sammyette]

website/themes/hsh/assets/css/syntax.css

@@ -1,15 +1,11 @@
-.chroma {
+/* Background */ .bg { background-color: #edfdff; }
-	display: inline-block;
+/* PreWrapper */ .chroma { background-color: #edfdff; }
-	padding: 0.5em;
-}
-/* Background */ .bg { background-color: #F7F7F7; }
-/* PreWrapper */ .chroma { background-color: #F7F7F7; }
 /* Other */ .chroma .x {  }
 /* Error */ .chroma .err { color: #a61717; background-color: #e3d2d2 }
 /* CodeLine */ .chroma .cl {  }
 /* LineTableTD */ .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; }
 /* LineTable */ .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; }
-/* LineHighlight */ .chroma .hl { background-color: #F7F7F7 }
+/* LineHighlight */ .chroma .hl { background-color: #edfdff }
 /* LineNumbersTable */ .chroma .lnt { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
 /* LineNumbers */ .chroma .ln { white-space: pre; user-select: none; margin-right: 0.4em; padding: 0 0.4em 0 0.4em;color: #7f7f7f }
 /* Line */ .chroma .line { display: flex; }

website/themes/hsh/layouts/partials/head.html

@@ -70,9 +70,5 @@
 	table tr {
 		border-width: 1px;
 	}
-
-	thead {
-		display: none;
-	}
 	</style>
 </head>