website(docs/commander): rewrite commander docs

docs/api/commander.md

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

emmyLuaDocs/commander.lua

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

golibs/commander/commander.go

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