From eaad02b4e7e0d6635f44d4aaa7d35abc09c37888 Mon Sep 17 00:00:00 2001
From: Emi Simpson <emi@alchemi.dev>
Date: Thu, 21 Oct 2021 14:38:37 -0400
Subject: [PATCH] Add crate-level docs

---
 src/lib.rs                  | 40 +++++++++++++++++++++++++++++++++++++
 src/user_preferences/mod.rs |  7 ++++---
 src/weighted_table.rs       |  4 ++--
 3 files changed, 46 insertions(+), 5 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 6ad2b64..9c1a4fb 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,43 @@
+//! The algorithms powering pronouns.today - Random pronouns generated daily
+//!
+//! This library contains all of the functionality for selecting a random pronoun based off of a
+//! user's preferences, including parsing various preference string (prefstring) versions,
+//! generating a weighted table based off of user preferences, and selecting a pronoun set based
+//! off of that weighted table.
+//!
+//! ## Basic Usage
+//!
+//! ```
+//! use pronouns_today::InstanceSettings;
+//!
+//! let instance_settings = InstanceSettings::default() // Or load from a config file
+//!
+//! // When you receive a request
+//! let user_name = Some("Emi");
+//! let user_prefstr = Some("acaqqbykawbag");
+//! let pronouns = instance_settings.select_pronouns(user_name, user_prefstr);
+//!
+//! println!("Your pronouns are: {}", pronouns);
+//! ```
+//!
+//! ## Advanced Usage
+//!
+//! The `InstanceSettings::select_pronouns()` method is really just a shorthand for the
+//! more complex process going on behind the scenes.  In reality, there are several steps
+//! used to select the pronouns.  Each step can be modified or run individually for
+//! greater control.
+//!
+//! 1. Configure the [`InstanceSettings`] from a config or default
+//! 2. Parse the user's prefstring with [`UserPreferences::from_prefstring()`][up]
+//! 3. Produce a weighted table from the preferences using
+//!    [`UserPreferences::into_weighted_table()`][up]
+//! 4. Roll a pronoun set from the weighted table with one of the methods in the
+//!    [`WeightedTable`] struct.
+//! 5. Render the [`Pronoun`]s with one of the provided methods, or use the forms
+//!    individually.
+//!
+//! [up]: UserPreferences
+
 pub mod user_preferences;
 mod weighted_table;
 
diff --git a/src/user_preferences/mod.rs b/src/user_preferences/mod.rs
index 3d358e5..6571159 100644
--- a/src/user_preferences/mod.rs
+++ b/src/user_preferences/mod.rs
@@ -33,9 +33,10 @@ pub trait Preference<'a> {
 
 	/// Produce a weighted list of pronouns based on these preferences
 	///
-	/// This is a one-directional conversion to a [`WeightedList`].  This method is a crucial step
-	/// to randomly selecting a pronoun set based on a user's preferences, as any selection is done
-	/// by using a [`WeightedList`].  All preference versions must implement this method.
+	/// This is a one-directional conversion to a [`WeightedTable`].  This method is a
+	/// crucial step to randomly selecting a pronoun set based on a user's preferences, as
+	/// any selection is done by using a [`WeightedTable`].  All preference versions must
+	/// implement this method.
 	fn into_weighted_table(&self) -> WeightedTable;
 
 	/// Parse a given prefstring, after it's extraction from base64
diff --git a/src/weighted_table.rs b/src/weighted_table.rs
index 30f7316..bbb0179 100644
--- a/src/weighted_table.rs
+++ b/src/weighted_table.rs
@@ -23,7 +23,7 @@ pub struct WeightedTable<'a>(pub Vec<(&'a Pronoun, u8)>);
 
 impl<'a> WeightedTable<'a> {
 
-	/// A shorthand for calling [`Preference::select_pronouns_on_date()`] with today's date
+	/// A shorthand for calling [`WeightedTable::select_on_date()`] with today's date
 	///
 	/// The date is generated for the system's time and timezone
 	pub fn select_today(&self, seed: &[u8]) -> &Pronoun {
@@ -37,7 +37,7 @@ impl<'a> WeightedTable<'a> {
 
 	/// Randomly select a pronoun set for a given date and name.
 	///
-	/// Is a wrapper for calling [`WeightedList::select`] with the given date mixed into the seed.
+	/// Is a wrapper for calling [`WeightedTable::select`] with the given date mixed into the seed.
 	pub fn select_on_date(&self, seed: &[u8], date: Date) -> &Pronoun {
 		let mut new_seed: Vec<u8> = Vec::with_capacity(seed.len() + 4);
 		new_seed.extend(