Add crate-level docs

This commit is contained in:
Emi Simpson 2021-10-21 14:38:37 -04:00
parent b04d8ed8bc
commit eaad02b4e7
Signed by: Emi
GPG Key ID: A12F2C2FFDC3D847
3 changed files with 46 additions and 5 deletions

View File

@ -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;

View File

@ -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

View File

@ -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(