From d457feb35f0c5a70bd0cc4911bd7aa680ca5ed91 Mon Sep 17 00:00:00 2001
From: _ <_@_>
Date: Sat, 17 Apr 2021 17:08:08 -0500
Subject: [PATCH] :pencil: docs: document ptth_core

---
 Cargo.lock                                |  2 +-
 crates/ptth_core/Cargo.toml               |  2 +-
 crates/ptth_core/src/graceful_shutdown.rs |  9 +++++++++
 crates/ptth_core/src/lib.rs               | 23 +++++++++++++++++++----
 4 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 162ff02..cf0a737 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1443,7 +1443,7 @@ dependencies = [
 
 [[package]]
 name = "ptth_core"
-version = "1.3.0"
+version = "1.4.0"
 dependencies = [
  "base64",
  "ctrlc",
diff --git a/crates/ptth_core/Cargo.toml b/crates/ptth_core/Cargo.toml
index 53a5149..13b557f 100644
--- a/crates/ptth_core/Cargo.toml
+++ b/crates/ptth_core/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 
 name = "ptth_core"
-version = "1.3.0"
+version = "1.4.0"
 authors = ["Trish"]
 edition = "2018"
 license = "AGPL-3.0"
diff --git a/crates/ptth_core/src/graceful_shutdown.rs b/crates/ptth_core/src/graceful_shutdown.rs
index 8b6dac1..de53adb 100644
--- a/crates/ptth_core/src/graceful_shutdown.rs
+++ b/crates/ptth_core/src/graceful_shutdown.rs
@@ -14,6 +14,8 @@ use tokio::{
 
 use crate::prelude::*;
 
+/// Initializes a graceful shutdown using the `ctrlc` crate
+
 #[must_use]
 pub fn init () -> oneshot::Receiver <()> {
 	let (tx, rx) = oneshot::channel::<()> ();
@@ -60,12 +62,17 @@ impl error::Error for ShutdownError {
 	
 }
 
+/// The type returned by `init_with_force`
+
 pub struct ForcedShutdown {
 	rx: oneshot::Receiver <()>,
 	tx: oneshot::Sender <()>,
 }
 
 impl ForcedShutdown {
+	/// Wraps a future in a graceful shutdown that times out into a 
+	/// forced shutdown.
+	/// 
 	/// # Errors
 	/// 
 	/// `ForcedShutdown` if the graceful shutdown doesn't complete in time
@@ -97,6 +104,8 @@ impl ForcedShutdown {
 	}
 }
 
+/// Initializes a graceful shutdown that times out into a forced shutdown
+
 #[must_use]
 pub fn init_with_force () -> (oneshot::Receiver <()>, ForcedShutdown) {
 	let (tx, rx) = oneshot::channel ();
diff --git a/crates/ptth_core/src/lib.rs b/crates/ptth_core/src/lib.rs
index e694746..bf16068 100644
--- a/crates/ptth_core/src/lib.rs
+++ b/crates/ptth_core/src/lib.rs
@@ -1,13 +1,24 @@
+//! # PTTH Core
+//! 
+//! Common code used by both `ptth_relay` and `ptth_server`.
+
 #![warn (clippy::pedantic)]
 
+/// Wrapper for graceful and forced shutdowns of `ptth_relay` and `ptth_server`
 pub mod graceful_shutdown;
+
+/// An abstraction over HTTP that is easy to (de)serialize
 pub mod http_serde;
+
 pub mod prelude;
 
-// It's easier if the server can stream its response body
-// back to the relay un-changed inside its request body
-// So we wrap the server's actual response head
-// (status code, headers, etc.) in this one header field.
+/// `ptth_server` packs its response headers into this request header
+/// 
+/// This allows the server's response body to be wrapped verbatim
+/// in the request body.
+/// The header value is the response's status code and headers,
+/// wrapped in a MessagePack structure, and encoded in base64
+/// to make it ASCII.
 
 pub const PTTH_MAGIC_HEADER: &str = "X-PTTH-2LJYXWC4";
 
@@ -15,6 +26,10 @@ pub const PTTH_MAGIC_HEADER: &str = "X-PTTH-2LJYXWC4";
 // e.g. prefix_match ("/prefix", "/prefix/middle/suffix") -> "/middle/suffix"
 
 #[must_use]
+#[deprecated (
+    since = "1.4.0",
+    note = "Use `str::strip_prefix instead`"
+)]
 pub fn prefix_match <'a> (prefix: &str, hay: &'a str) -> Option <&'a str>
 {
 	hay.strip_prefix (prefix)