📝 docs: document ptth_core

Cargo.lock

@@ -1443,7 +1443,7 @@ dependencies = [
 
 [[package]]
 name = "ptth_core"
-version = "1.3.0"
+version = "1.4.0"
 dependencies = [
  "base64",
  "ctrlc",

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"

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 ();

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
+/// `ptth_server` packs its response headers into this request header
-// back to the relay un-changed inside its request body
+/// 
-// So we wrap the server's actual response head
+/// This allows the server's response body to be wrapped verbatim
-// (status code, headers, etc.) in this one header field.
+/// 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)