fix: missing func docs and generate example in code block

cmd/docgen/docgen.lua

@@ -41,10 +41,12 @@ for _, fname in ipairs(files) do
 
 				local dps = {
 					description = {},
+					example = {},
 					params = {}
 				}
 
 				local offset = 1
+				local doingExample = false
 				while true do
 					local prev = lines[lineno - offset]
 
@@ -66,7 +68,17 @@ for _, fname in ipairs(files) do
 								})
 							end
 						else
-							table.insert(dps.description, 1, docline)
+							if docline:match '#example' then
+								doingExample = not doingExample
+							end
+
+							if not docline:match '#example' then
+								if doingExample then
+										table.insert(dps.example, 1, docline)
+								else
+									table.insert(dps.description, 1, docline)
+								end
+							end
 						end
 						offset = offset + 1
 					else
@@ -187,6 +199,10 @@ for iface, dps in pairs(pieces) do
 			f:write(string.format('`%s` **`%s`**  \n', param.name:gsub('%?$', ''), param.type))
 			f:write(string.format('%s\n\n', param.description))
 		end
+		if #docs.example ~= 0 then
+			f:write '#### Example\n'
+			f:write(string.format('```lua\n%s\n```\n', table.concat(docs.example, '\n')))
+		end
 		--[[
 		local params = table.filter(docs, function(t)
 			return t:match '^%-%-%- @param'

docs/api/hilbish/_index.md

@@ -31,6 +31,7 @@ interfaces and functions which directly relate to shell functionality.
 |<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.|
 |<a href="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish.|
+|<a href="#run">run(cmd, streams)</a>|Runs `cmd` in Hilbish's shell script interpreter.|
 
 ## Static module fields
 |||
@@ -474,6 +475,44 @@ Writes data to a sink.
 #### writeln(str)
 Writes data to a sink with a newline at the end.
 
+<hr>
+<div id='run'>
+<h4 class='heading'>
+hilbish.run(cmd, streams)
+<a href="#run" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Runs `cmd` in Hilbish's shell script interpreter.
+The `streams` parameter 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
+`cmd` **`string`**  
+
+
+`streams` **`table|boolean`**  
+
+
+#### Example
+```lua
+This code is the same as `ls -l | wc -l`
+local fs = require 'fs'
+local pr, pw = fs.pipe()
+hilbish.run('ls -l', {
+	stdout = pw,
+	stderr = pw,
+})
+pw:close()
+hilbish.run('wc -l', {
+	stdin = pr
+})
+```
+</div>
+
 <hr>
 <div id='runnerMode'>
 <h4 class='heading'>

docs/api/hilbish/hilbish.jobs.md

@@ -1,146 +0,0 @@
----
-title: Module hilbish.jobs
-description: background job management
-layout: doc
-menu:
-  docs:
-    parent: "API"
----
-
-## Introduction
-
-Manage interactive jobs in Hilbish via Lua.
-
-Jobs are the name of background tasks/commands. A job can be started via
-interactive usage or with the functions defined below for use in external runners.
-
-## Functions
-|||
-|----|----|
-|<a href="#jobs.add">add(cmdstr, args, execPath)</a>|Creates a new job. This function does not run the job. This function is intended to be|
-|<a href="#jobs.all">all() -> table[@Job]</a>|Returns a table of all job objects.|
-|<a href="#jobs.disown">disown(id)</a>|Disowns a job. This simply deletes it from the list of jobs without stopping it.|
-|<a href="#jobs.get">get(id) -> @Job</a>|Get a job object via its ID.|
-|<a href="#jobs.last">last() -> @Job</a>|Returns the last added job to the table.|
-
-<hr>
-<div id='jobs.add'>
-<h4 class='heading'>
-hilbish.jobs.add(cmdstr, args, execPath)
-<a href="#jobs.add" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-Creates a new job. This function does not run the job. This function is intended to be  
-used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.  
-
-#### Parameters
-`string` **`cmdstr`**  
-String that a user would write for the job
-
-`table` **`args`**  
-Arguments for the commands. Has to include the name of the command.
-
-`string` **`execPath`**  
-Binary to use to run the command. Needs to be an absolute path.
-
-#### Example
-```lua
-hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go')
-```
-</div>
-
-<hr>
-<div id='jobs.all'>
-<h4 class='heading'>
-hilbish.jobs.all() -> table[<a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>]
-<a href="#jobs.all" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-Returns a table of all job objects.  
-
-#### Parameters
-This function has no parameters.  
-</div>
-
-<hr>
-<div id='jobs.disown'>
-<h4 class='heading'>
-hilbish.jobs.disown(id)
-<a href="#jobs.disown" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-Disowns a job. This simply deletes it from the list of jobs without stopping it.  
-
-#### Parameters
-`number` **`id`**  
-
-
-</div>
-
-<hr>
-<div id='jobs.get'>
-<h4 class='heading'>
-hilbish.jobs.get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>
-<a href="#jobs.get" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-Get a job object via its ID.  
-
-#### Parameters
-This function has no parameters.  
-</div>
-
-<hr>
-<div id='jobs.last'>
-<h4 class='heading'>
-hilbish.jobs.last() -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>
-<a href="#jobs.last" class='heading-link'>
-	<i class="fas fa-paperclip"></i>
-</a>
-</h4>
-
-Returns the last added job to the table.  
-
-#### Parameters
-This function has no parameters.  
-</div>
-
-## Types
-<hr>
-
-## Job
-The Job type describes a Hilbish job.
-## Object properties
-|||
-|----|----|
-|cmd|The user entered command string for the job.|
-|running|Whether the job is running or not.|
-|id|The ID of the job in the job table|
-|pid|The Process ID|
-|exitCode|The last exit code of the job.|
-|stdout|The standard output of the job. This just means the normal logs of the process.|
-|stderr|The standard error stream of the process. This (usually) includes error messages of the job.|
-
-
-### Methods
-#### background()
-Puts a job in the background. This acts the same as initially running a job.
-
-#### foreground()
-Puts a job in the foreground. This will cause it to run like it was
-executed normally and wait for it to complete.
-
-#### start()
-Starts running the job.
-
-#### stop()
-Stops the job from running.
-

docs/api/hilbish/hilbish.os.md

@@ -1,20 +0,0 @@
----
-title: Module hilbish.os
-description: operating system info
-layout: doc
-menu:
-  docs:
-    parent: "API"
----
-
-## Introduction
-Provides simple text information properties about the current operating system.
-This mainly includes the name and version.
-
-## Static module fields
-|||
-|----|----|
-|family|Family name of the current OS|
-|name|Pretty name of the current OS|
-|version|Version of the current OS|
-

nature/hilbish.lua

@@ -1,3 +1,4 @@
+-- @module hilbish
 local hilbish = require 'hilbish'
 local snail = require 'snail'
 
@@ -9,9 +10,6 @@ hilbish.snail = snail.new()
 --- 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.
---- #param cmd string
---- #param streams table|boolean
---- #returns number, string, string
 --- #example
 --- This code is the same as `ls -l | wc -l`
 --- local fs = require 'fs'
@@ -25,6 +23,9 @@ hilbish.snail = snail.new()
 --- 	stdin = pr
 --- })
 --- #example
+-- @param cmd string
+-- @param streams table|boolean
+-- @returns number, string, string
 function hilbish.run(cmd, streams)
 	local sinks = {}
 
@@ -50,3 +51,26 @@ function hilbish.run(cmd, streams)
 
 	return table.unpack(returns)
 end
+
+--- Sets the execution/runner mode for interactive Hilbish.
+--- **NOTE: This function is deprecated and will be removed in 3.0**
+--- Use `hilbish.runner.setCurrent` instead.
+--- This determines whether Hilbish wll try to run input as Lua
+--- and/or sh or only do one of either.
+--- Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),
+--- sh, and lua. It also accepts a function, to which if it is passed one
+--- will call it to execute user input instead.
+--- Read [about runner mode](../features/runner-mode) for more information.
+-- @param mode string|function
+function hilbish.runnerMode(mode)
+	if type(mode) == 'string' then
+		hilbish.runner.setCurrent(mode)
+	elseif type(mode) == 'function' then
+		hilbish.runner.set('_', {
+			run = mode
+		})
+		hilbish.runner.setCurrent '_'
+	else
+		error('expected runner mode type to be either string or function, got', type(mode))
+	end
+end

nature/init.lua

@@ -18,7 +18,7 @@ table.insert(package.searchers, function(module)
 	return function() return hilbish.module.load(path) end, path
 end)
 
-require 'nature.snail'
+require 'nature.hilbish'
 
 require 'nature.commands'
 require 'nature.completions'

nature/runnerLegacy.lua

@@ -1,24 +0,0 @@
--- @module hilbish
-
---- Sets the execution/runner mode for interactive Hilbish.
---- **NOTE: This function is deprecated and will be removed in 3.0**
---- Use `hilbish.runner.setCurrent` instead.
---- This determines whether Hilbish wll try to run input as Lua
---- and/or sh or only do one of either.
---- Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),
---- sh, and lua. It also accepts a function, to which if it is passed one
---- will call it to execute user input instead.
---- Read [about runner mode](../features/runner-mode) for more information.
--- @param mode string|function
-function hilbish.runnerMode(mode)
-	if type(mode) == 'string' then
-		hilbish.runner.setCurrent(mode)
-	elseif type(mode) == 'function' then
-		hilbish.runner.set('_', {
-			run = mode
-		})
-		hilbish.runner.setCurrent '_'
-	else
-		error('expected runner mode type to be either string or function, got', type(mode))
-	end
-end