Add crate-level docs
This commit is contained in:
parent
b04d8ed8bc
commit
eaad02b4e7
40
src/lib.rs
40
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;
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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(
|
||||
|
|
Loading…
Reference in New Issue