Add documentation to intl-memoizer (#275)

Author: gregtatum

intl-memoizer/README.md

@@ -13,35 +13,44 @@ APIs such as `PluralRules`, DateTimeFormat` etc. between all `FluentBundle` inst
 Usage
 -----
 
+The following is a high-level example of how this works, for running examples see
+the [docs](https://docs.rs/intl-memoizer/)
+
 ```rust
-use intl_memoizer::{IntlMemoizer, Memoizable};
-use unic_langid::langid;
+/// Internationalization formatter should implement the Memoizable trait.
+impl Memoizable for NumberFormat {
+  ...
+}
 
-use intl_pluralrules::{PluralRules, PluralRuleType, PluralCategory};
+// The main memoizer has weak references to all of the per-language memoizers.
+let mut memoizer = IntlMemoizer::default();
 
-impl Memoizable for PluralRules {
-    type Args = (PluralRulesType,);
-    fn construct(lang: LanguageIdentifier, args: Self::Args) -> Self {
-      Self::new(lang, args.0)
-    }
-}
+// The formatter memoziation happens per-locale.
+let lang = "en-US".parse().expect("Failed to parse.");
+let lang_memoizer: Rc<IntlLangMemoizer> = memoizer.get_for_lang(en_us);
 
-fn main() {
-    let lang = langid!("en-US");
+// Run the formatter
 
-    // A single memoizer for all languages
-    let mut memoizer = IntlMemoizer::new();
+let options: NumberFormatOptions {
+    minimum_fraction_digits: 3,
+    maximum_fraction_digits: 5,
+};
 
-    // A RefCell for a particular language to be used in all `FluentBundle`
-    // instances.
-    let mut en_us_memoizer = memoizer.get_for_lang(lang.clone());
+// Format pi with the options. This will lazily construct the NumberFormat.
+let pi = lang_memoizer
+    .with_try_get::<NumberFormat, _, _>((options,), |nf| nf.format(3.141592653))
+    .unwrap()
 
-    // Per-call borrow
-    let mut en_us_memoizer_borrow = en_us_memoizer.borrow_mut();
-    let cb = en_us_memoizer_borrow.get::<PluralRules>((PluralRulesType::Cardinal,));
-    assert_eq!(cb.select(1), PluralCategory::One);
-}
+// The example formatter constructs a string with diagnostic information about
+// the configuration.
+assert_eq!(text, "3.14159");
+
+// Running it again will use the previous formatter.
+let two = lang_memoizer
+    .with_try_get::<NumberFormat, _, _>((options,), |nf| nf.format(2.0))
+    .unwrap()
 
+assert_eq!(text, "2.000");
 ```
 
 Get Involved

intl-memoizer/src/concurrent.rs

@@ -1,20 +1,27 @@
+//! Contains thread-safe variants.
 use super::*;
 use std::sync::Mutex;
 
+/// A thread-safe version of the [`intl_memoizer::IntlLangMemoizer`](super::IntlLangMemoizer).
+/// See the single-thread version for more documentation.
 #[derive(Debug)]
 pub struct IntlLangMemoizer {
     lang: LanguageIdentifier,
     map: Mutex<type_map::concurrent::TypeMap>,
 }
 
 impl IntlLangMemoizer {
+    /// Create a new [`IntlLangMemoizer`] that is unique to a specific [`LanguageIdentifier`]
     pub fn new(lang: LanguageIdentifier) -> Self {
         Self {
             lang,
             map: Mutex::new(type_map::concurrent::TypeMap::new()),
         }
     }
 
+    /// Lazily initialize and run a formatter. See
+    /// [`intl_memoizer::IntlLangMemoizer::with_try_get`](../struct.IntlLangMemoizer.html#method.with_try_get)
+    /// for documentation.
     pub fn with_try_get<I, R, U>(&self, args: I::Args, cb: U) -> Result<R, I::Error>
     where
         Self: Sized,