docs: updated readmes

3 files changed, 88 insertions, 10 deletions

diff --git a/angelsharkd/src/routes/extensions/README.md b/angelsharkd/src/routes/extensions/README.md
index b9192fe..1aed1dd 100644
--- a/angelsharkd/src/routes/extensions/README.md
+++ b/angelsharkd/src/routes/extensions/README.md
@@ -1,12 +1,13 @@
 # Angelshark Daemon Extensions
 
-This module aims to provide a simple way of extending Angelshark's basic functionality (running commands on the ACM) with additional HTTP endpoints that run one or more commands to achieve a basic business task. 
+This module aims to provide a simple way of extending Angelshark's basic
+functionality (running commands on the ACM) with additional HTTP endpoints that
+run one or more commands to achieve a basic business task.
 
-For example, say you would like you, other users, or your own software to quickly search all extension-types for a keyword. This functionality is not in the base `angelsharkd`, but it can be easily implemented with the following steps:
+This functionality may not be desirable for all end users, and therefore is
+completely opt-in with feature flags. For example, at compile time, you can add
+`--features simple_search` to enable a given extension called `simple_search`.
 
-1. Accept a keyword from the client's request
-1. Download extension-type data from one or more ACMs
-1. Filter out extensions that do not match a given keyword
-1. Return the remaining, matching extensions to the client
-
-This functionality may not be desirable for all end users, and therefor is completely opt-in with feature flags. At compile time, you can add `--features simple_search` to enable a given extension called `simple_search`, for example.
+To add additional features, read `mod.rs` and `Cargo.toml` for `angelsharkd` to
+see how to conditionally incorporate your own warp HTTP filters into the
+project.
diff --git a/angelsharkd/src/routes/extensions/simple_search/README.md b/angelsharkd/src/routes/extensions/simple_search/README.md
index 527f686..c0df17a 100644
--- a/angelsharkd/src/routes/extensions/simple_search/README.md
+++ b/angelsharkd/src/routes/extensions/simple_search/README.md
@@ -1,3 +1,79 @@
-# Angelshark Simple Extension Search
+# Daemon Extension `simple_search`
 
-This extension implements very simple extension searching for end users. It allows for multi-keyword searches on a pre-downloaded collection of CM extension-type and station data. This data can be refreshed on-demand or periodically. Searches always return immediately, even when no data has been downloaded yet.
+This extension implements fast and simple extension searching for clients. Data
+to be searched is downloaded from configured ACMs as a "haystack." Clients pass
+a list of one or more "needles" to search for. Haystack entries matching all
+provided needles are returned.
+
+The haystack starts out empty. To trigger a download, use the `refresh`
+endpoint. Refreshes happen in the background, so clients always receive an
+immediate response. This means that clients will be searching on "stale" data
+(or on the first run, no data) until the refresh completes.
+
+There is no built-in scheduler for periodic haystack refreshes. It is
+recommended to use an external scheduler such as `cron(8)`.
+
+## Getting Started
+
+To enable this feature, compile `angelsharkd` with the `simple_search` flag:
+
+```sh
+cargo build --bin angelsharkd --features simple_search ...
+```
+
+This extension expects a single environment variable,
+`ANGELSHARKD_EXT_SEARCH_ACMS`, to be set at runtime. This var should be a list
+of ACM names from your `asa.cfg`. For example, if your `asa.cfg` is configured
+for ACMs named 01, 02, and 03, and you want to search over 01 and 03, run
+`angelsharkd` like this:
+
+```
+ANGELSHARKD_ADDR='127.0.0.1:3000' ANGELSHARKD_EXT_SEARCH_ACMS='01 03' angelsharkd
+```
+
+## `GET /extensions/search/refresh` Refresh Haystack
+
+`GET /extensions/search/refresh`
+
+```
+200 OK text/plain
+Refresh scheduled.
+```
+
+## `POST /extensions/search` Search Haystack
+
+The return type is the entire list of fields from the `list extension-type`
+command, the ROOM field from the `list station` command, and the configured name
+of the ACM the entry was found on.
+
+```json
+POST /extensions/search
+[
+	"carpenat"
+]
+```
+
+```json
+200 OK
+[
+    [
+        "17571230000",
+        "station-user",
+        "5",
+        "1",
+        "1005",
+        "Carpenter, Adam",
+        "2",
+        "",
+        "CM01",
+        "carpenat"
+    ],
+	...
+]
+```
+
+## Logging
+
+The `refresh` endpoint always returns successfully. Any errors encountered
+during the refresh are logged as `ERROR`. Successful completed refreshes are
+logged as `INFO`.
diff --git a/angelsharkd/src/routes/extensions/simple_search/types.rs b/angelsharkd/src/routes/extensions/simple_search/types.rs
index 184b1a6..72156e5 100644
--- a/angelsharkd/src/routes/extensions/simple_search/types.rs
+++ b/angelsharkd/src/routes/extensions/simple_search/types.rs
@@ -60,6 +60,7 @@ impl Haystack {
     /// Refreshes the haystack data by running relevant commands on a runner,
     /// parsing the results, and updating the entries field with the fresh data.
     /// TODO: Do we want simultaneous refreshes to be possible?
+    /// TODO: The entry generation could probably be simplified and the number of clones reduced.
     pub fn refresh(&self) -> Result<(), Error> {
         let mut runner = self.runner.to_owned();