fix: update docs

- warn if function is undocumented
- add docs for fs.pipe

cmd/docgen/docgen.go

@@ -488,7 +488,11 @@ func main() {
 					}
 
 					mdTable.SetContent(i - diff, 0, fmt.Sprintf(`<a href="#%s">%s</a>`, dps.FuncName, dps.FuncSig))
-					mdTable.SetContent(i - diff, 1, dps.Doc[0])
+					if len(dps.Doc) == 0 {
+						fmt.Printf("WARNING! Function %s on module %s has no documentation!\n", dps.FuncName, modname)
+					} else {
+						mdTable.SetContent(i - diff, 1, dps.Doc[0])
+					}
 				}
 				f.WriteString(mdTable.String())
 				f.WriteString("\n")

docs/api/commander.md

@@ -26,8 +26,11 @@ 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?
 
-The `sinks` parameter is a table with 3 keys: `in`, `out`,
+The `sinks` parameter is a table with 3 keys: `input`, `out`, and `err`.
-and `err`. All of them are a <a href="/Hilbish/docs/api/hilbish/#sink" style="text-decoration: none;">Sink</a>.
+There is an `in` alias to `input`, but it requires using the string accessor syntax (`sinks['in']`)
+as `in` is also a Lua keyword, so `input` is preferred for use.
+All of them are a <a href="/Hilbish/docs/api/hilbish/#sink" style="text-decoration: none;">Sink</a>.
+In the future, `sinks.in` will be removed.
 
 - `in` is the standard input.
 You may use the read functions on this sink to get input from the user.

docs/api/fs.md

@@ -23,6 +23,7 @@ library offers more functions and will work on any operating system Hilbish does
 |<a href="#glob">glob(pattern) -> matches (table)</a>|Match all files based on the provided `pattern`.|
 |<a href="#join">join(...path) -> string</a>|Takes any list of paths and joins them based on the operating system's path separator.|
 |<a href="#mkdir">mkdir(name, recursive)</a>|Creates a new directory with the provided `name`.|
+|<a href="#pipe">fpipe() -> File, File</a>|Returns a pair of connected files, also known as a pipe.|
 |<a href="#readdir">readdir(path) -> table[string]</a>|Returns a list of all files and directories in the provided path.|
 |<a href="#stat">stat(path) -> {}</a>|Returns the information about a given `path`.|
 
@@ -183,6 +184,22 @@ fs.mkdir('./foo/bar', true)
 ```
 </div>
 
+<hr>
+<div id='pipe'>
+<h4 class='heading'>
+fs.fpipe() -> File, File
+<a href="#pipe" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Returns a pair of connected files, also known as a pipe.  
+The type returned is a Lua file, same as returned from `io` functions.  
+
+#### Parameters
+This function has no parameters.  
+</div>
+
 <hr>
 <div id='readdir'>
 <h4 class='heading'>

docs/api/hilbish/_index.md

@@ -28,7 +28,7 @@ interfaces and functions which directly relate to shell functionality.
 |<a href="#prependPath">prependPath(dir)</a>|Prepends `dir` to $PATH.|
 |<a href="#prompt">prompt(str, typ)</a>|Changes the shell prompt to the provided string.|
 |<a href="#read">read(prompt) -> input (string)</a>|Read input from the user, using Hilbish's line editor/input reader.|
-|<a href="#run">run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)</a>|Runs `cmd` in Hilbish's shell script interpreter.|
+|<a href="#run">run(cmd, streams) -> exitCode (number), stdout (string), stderr (string)</a>|Runs `cmd` in Hilbish's shell script interpreter.|
 |<a href="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish.|
 |<a href="#timeout">timeout(cb, time) -> @Timer</a>|Executed the `cb` function after a period of `time`.|
 |<a href="#which">which(name) -> string</a>|Checks if `name` is a valid command.|
@@ -413,20 +413,25 @@ Text to print before input, can be empty.
 <hr>
 <div id='run'>
 <h4 class='heading'>
-hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)
+hilbish.run(cmd, streams) -> exitCode (number), stdout (string), stderr (string)
 <a href="#run" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
 </h4>
 
 Runs `cmd` in Hilbish's shell script interpreter.  
+Specifies the output and input streams the command should use.  
+For example, to write command output to a sink.  
+As a table, the caller can directly specify the standard output, error, and input  
+streams of the command with the table keys `out`, `err`, and `input` respectively.  
+As a boolean, it specifies whether the command should use standard output or return its output streams.  
 
 #### Parameters
 `string` **`cmd`**  
 
 
-`boolean` **`returnOut`**  
+`table|boolean` **`streams`**  
-If this is true, the function will return the standard output and error of the command instead of printing it.
+
 
 </div>
 

emmyLuaDocs/fs.lua

@@ -34,6 +34,10 @@ function fs.join(...path) end
 --- 
 function fs.mkdir(name, recursive) end
 
+--- Returns a pair of connected files, also known as a pipe.
+--- The type returned is a Lua file, same as returned from `io` functions.
+function fs.fpipe() end
+
 --- Returns a list of all files and directories in the provided path.
 function fs.readdir(path) end
 

emmyLuaDocs/hilbish.lua

@@ -132,7 +132,12 @@ function hilbish.prompt(str, typ) end
 function hilbish.read(prompt) end
 
 --- Runs `cmd` in Hilbish's shell script interpreter.
-function hilbish.run(cmd, returnOut) end
+--- Specifies the output and input streams the command should use.
+--- For example, to write command output to a sink.
+--- As a table, the caller can directly specify the standard output, error, and input
+--- streams of the command with the table keys `out`, `err`, and `input` respectively.
+--- As a boolean, it specifies whether the command should use standard output or return its output streams.
+function hilbish.run(cmd, streams) end
 
 --- Sets the execution/runner mode for interactive Hilbish.
 --- This determines whether Hilbish wll try to run input as Lua

golibs/fs/fs.go

@@ -228,6 +228,11 @@ func fmkdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), err
 }
 
+// fpipe() -> File, File
+// Returns a pair of connected files, also known as a pipe.
+// The type returned is a Lua file, same as returned from `io` functions.
+// #returns File
+// #returns File
 func fpipe(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	rf, wf, err := os.Pipe()
 	if err != nil {