From 1fd99a78cca2ff3d5f40413621df2b90c62c0eb2 Mon Sep 17 00:00:00 2001
From: TorchedSammy <38820196+TorchedSammy@users.noreply.github.com>
Date: Sat, 21 May 2022 20:33:05 -0400
Subject: [PATCH] docs: add docs and changelogs relating to jobs

---
 CHANGELOG.md       | 13 +++++++++++++
 docs/hooks/job.txt | 10 ++--------
 docs/jobs.txt      | 40 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 55 insertions(+), 8 deletions(-)
 create mode 100644 docs/jobs.txt

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f350cff..f2f7850 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,17 @@ is for everything/anything as opposed to just adding a single command completion
 [#122](https://github.com/Rosettea/Hilbish/issues/122)
 - `fs.abs(path)` to get absolute path.
 - Nature module (`doc nature`)
+- `hilbish.jobs.add(cmdstr, args, execPath)` to add a job to the job table.
+`cmdstr` would be user input, `args` is the args for the command (includes arg0)
+and `execPath` is absolute path to command executable
+- `job.add` hook is thrown when a job is added. acts as a unique hook for
+jobs
+- `hilbish.jobs.disown(id)` and `disown` builtin to disown a job. `disown`
+without arguments will disown the last job.
+- `hilbish.jobs.last()` returns the last added job.
+- Job output (stdout/stderr) can now be obtained via the `stdout` and `stderr`
+fields on a job object.
+- Documentation for jobs is now available via `doc jobs`.
 
 ### Changed
 - **Breaking Change:** Upgraded to Lua 5.4.
@@ -57,6 +68,8 @@ certain color rules.
 - Cursor position with CJK characters. ([#145](https://github.com/Rosettea/Hilbish/pull/145))
 - Files with same name as parent folder in completions getting cut off [#136](https://github.com/Rosettea/Hilbish/issues/136))
 - `hilbish.which` now works with commanders and aliases.
+- Background jobs no longer take stdin so they do not interfere with shell
+input.
 
 ## [1.2.0] - 2022-03-17
 ### Added
diff --git a/docs/hooks/job.txt b/docs/hooks/job.txt
index 497df1c..cbef74f 100644
--- a/docs/hooks/job.txt
+++ b/docs/hooks/job.txt
@@ -1,11 +1,5 @@
-Note: A `job` is a table with the following keys:
-- cmd: command string
-- running: boolean whether the job is running
-- id: unique id for the job
-- pid: process id for the job
-- exitCode: exit code of the job
-In ordinary cases you'd prefer to use the id instead of pid. The id is unique to
-Hilbish and is how you get jobs with the `hilbish.jobs` interface.
+Note: `job` refers to a job object. YOu can check `doc jobs` for more
+detail.
 
 + `job.start` -> job > Thrown when a new background job starts.
 
diff --git a/docs/jobs.txt b/docs/jobs.txt
new file mode 100644
index 0000000..0074931
--- /dev/null
+++ b/docs/jobs.txt
@@ -0,0 +1,40 @@
+Hilbish has pretty standard job control. It's missing one or two things,
+but works well. One thing which is different from other shells
+(besides Hilbish) itself is the API for jobs, and of course it's in Lua.
+You can add jobs, stop and delete (disown) them and even get output.
+
+# Job Interface
+The job interface refers to `hilbish.jobs`.
+## Functions
+(Note that in the list here, they're called from `hilbish.jobs`, so
+a listing of `foo` would mean `hilbish.jobs.foo`)
+
+- `all()` -> {jobs}: Returns a table of all jobs.
+- `last()` -> job: Returns the last added job.
+- `get(id)` -> job: Get a job by its ID.
+- `add(cmdstr, args, execPath)` -> job: Adds a new job to the job table.
+Note that this does not run the command; You have to start it manually.
+`cmdstr` is the user's input for the job, `args` is a table of arguments
+for the command. It includes arg0 (don't set it as entry 0 in the table)
+and `execPath` is an absolute path for the command executable.
+- `disown(id)`: Removes a job by ID from the job table.
+
+# Job Object
+A job object on the Lua side is a table with some functions.
+On the under side it represents a job in the job table.
+You can still have a job object for a disowned job,
+it just won't be *working* anywhere. :^)
+
+## Properties
+- `cmd`: command string
+- `running`: boolean whether the job is running
+- `id`: unique id for the job
+- `pid`: process id for the job
+- `exitCode`: exit code of the job
+In ordinary cases you'd prefer to use the `id` instead of `pid`.
+The `id` is unique to Hilbish and is how you get jobs with the
+`hilbish.jobs` interface. It may also not describe the job entirely.
+
+## Functions
+- `stop()`: Stops the job.
+- `start()`: Starts the job.