Add docs for FluentBundle

Added docs for FluentBundle. Also, corrected some errors in the pre-existing docs.

Author: JohnHeitmann

fluent/src/bundle.rs

@@ -22,21 +22,40 @@ pub struct Message {
     pub attributes: HashMap<String, String>,
 }
 
-/// `FluentBundle` is a collection of localization messages which are meant to be used together
-/// in a single view, widget or any other UI abstraction.
+/// A collection of localization messages for a single locale, which are meant
+/// to be used together in a single view, widget or any other UI abstraction.
 ///
-/// # `FluentBundle` Life-cycle
+/// # Examples
 ///
-/// To create a bundle, call `FluentBundle::new` with a locale list that represents the best
-/// possible fallback chain for a given locale.  The simplest case is a one-locale list.
+/// ```
+/// use fluent::bundle::FluentBundle;
+/// use fluent::types::FluentValue;
+/// use std::collections::HashMap;
 ///
-/// Next, call `add_messages` one or more times, supplying translations in the FTL syntax. The
+/// let mut bundle = FluentBundle::new(&["en-US"]);
+/// bundle.add_messages("intro = Welcome, { $name }.");
+///
+/// let mut args = HashMap::new();
+/// args.insert("name", FluentValue::from("John"));
+///
+/// let value = bundle.format("intro", Some(&args));
+/// assert_eq!(value, Some(("Welcome, John.".to_string(), vec![])));
+///
+/// ```
+///
+/// # `FluentBundle` Life Cycle
+///
+/// To create a bundle, call [`FluentBundle::new`] with a locale list that represents the best
+/// possible fallback chain for a given locale. The simplest case is a one-locale list.
+///
+/// Next, call [`add_messages`] one or more times, supplying translations in the FTL syntax. The
 /// `FluentBundle` instance is now ready to be used for localization.
 ///
-/// To format a translation, call `get_message` to retrieve a `fluent::bundle::Message` structure
-/// and then `format` it within the bundle.
+/// To format a translation, call [`format`] with a message id or path (a path is a message id
+/// plus an attribute, e.g. 'hello-world.tooltip').
 ///
-/// The result is an Option wrapping a single string that should be displayed in the UI.  It is
+/// The result is an [`Option<T>`] wrapping a `(String, Vec<FluentError>)`. On success, the string
+/// is a formatted value that should be displayed in the UI.  It is
 /// recommended to treat the result as opaque from the perspective of the program and use it only
 /// to display localized messages. Do not examine it or alter in any way before displaying.  This
 /// is a general good practice as far as all internationalization operations are concerned.
@@ -48,6 +67,13 @@ pub struct Message {
 /// purpose of language negotiation with i18n formatters. For instance, if date and time formatting
 /// are not available in the first locale, `FluentBundle` will use its `locales` fallback chain
 /// to negotiate a sensible fallback for date and time formatting.
+///
+/// [`add_messages`]: ./struct.FluentBundle.html#method.add_messages
+/// [`FluentBundle::new`]: ./struct.FluentBundle.html#method.new
+/// [`fluent::bundle::Message`]: ./struct.FluentBundle.html#method.new
+/// [`format`]: ./struct.FluentBundle.html#method.format
+/// [`get_message`]: ./struct.FluentBundle.html#method.get_message
+/// [`Option<T>`]: http://doc.rust-lang.org/std/option/enum.Option.html
 #[allow(dead_code)]
 pub struct FluentBundle<'bundle> {
     pub locales: Vec<String>,
@@ -56,6 +82,21 @@ pub struct FluentBundle<'bundle> {
 }
 
 impl<'bundle> FluentBundle<'bundle> {
+    /// Constructs a FluentBundle. `locales` is the fallback chain of locales
+    /// to use for formatters like date and time. `locales` does not influence
+    /// message selection.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use fluent::bundle::FluentBundle;
+    ///
+    /// let mut bundle = FluentBundle::new(&["en-US"]);
+    /// ```
+    ///
+    /// # Errors
+    ///
+    /// This will panic if no formatters can be found for the locales.
     pub fn new<'a, S: ToString>(locales: &'a [S]) -> FluentBundle<'bundle> {
         let locales = locales
             .into_iter()
@@ -77,10 +118,48 @@ impl<'bundle> FluentBundle<'bundle> {
         }
     }
 
+    /// Returns true if this bundle contains a message with the given id.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use fluent::bundle::FluentBundle;
+    ///
+    /// let mut bundle = FluentBundle::new(&["en-US"]);
+    /// bundle.add_messages("hello = Hi!");
+    /// assert_eq!(true, bundle.has_message("hello"));
+    /// ```
     pub fn has_message(&self, id: &str) -> bool {
         self.entries.get_message(id).is_some()
     }
 
+    /// Makes the provided rust function available to messages with the name `id`. See
+    /// the [FTL syntax guide] to learn how these are used in messages.
+    ///
+    /// FTL functions accept both positional and named args. The rust function you
+    /// provide therefore has two parameters: a slice of values for the positional
+    /// args, and a HashMap of values for named args.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use fluent::bundle::FluentBundle;
+    /// use fluent::types::FluentValue;
+    ///
+    /// let mut bundle = FluentBundle::new(&["en-US"]);
+    ///
+    /// // Register a fn that maps from string to string length
+    /// bundle.add_function("STRLEN", |positional, named| match positional {
+    ///     [Some(FluentValue::String(str))] => Some(FluentValue::Number(str.len().to_string())),
+    ///     _ => None,
+    /// }).unwrap();
+    ///
+    /// bundle.add_messages("length = { STRLEN(\"12345\") }").unwrap();
+    /// let (value, _) = bundle.format("length", None).unwrap();
+    /// assert_eq!(&value, "5");
+    /// ```
+    ///
+    /// [FTL syntax guide]: https://projectfluent.org/fluent/guide/functions.html
     pub fn add_function<F>(&mut self, id: &str, func: F) -> Result<(), FluentError>
     where
         F: 'bundle
@@ -100,6 +179,33 @@ impl<'bundle> FluentBundle<'bundle> {
         }
     }
 
+    /// Adds the message or messages, in [FTL syntax], to the bundle, returning an
+    /// empty [`Result<T>`] on success.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use fluent::bundle::FluentBundle;
+    ///
+    /// let mut bundle = FluentBundle::new(&["en-US"]);
+    /// bundle.add_messages("
+    /// hello = Hi!
+    /// goodbye = Bye!
+    /// ");
+    /// assert_eq!(true, bundle.has_message("hello"));
+    /// ```
+    ///
+    /// # Whitespace
+    ///
+    /// Message ids must have no leading whitespace. Message values that span
+    /// multiple lines must have leading whitespace on all but the first line. These
+    /// are standard FTL syntax rules that may prove a bit troublesome in source
+    /// code formatting. The [`indoc!`] crate can help with stripping extra indentation
+    /// if you wish to indent your entire message.
+    ///
+    /// [FTL syntax]: https://projectfluent.org/fluent/guide/
+    /// [`indoc!`]: https://github.com/dtolnay/indoc
+    /// [`Result<T>`]: https://doc.rust-lang.org/std/result/enum.Result.html
     pub fn add_messages(&mut self, source: &str) -> Result<(), Vec<FluentError>> {
         match FluentResource::from_string(source) {
             Ok(res) => self.add_resource(res),
@@ -117,6 +223,7 @@ impl<'bundle> FluentBundle<'bundle> {
         }
     }
 
+    /// Use [`add_messages`](./struct.FluentBundle.html#method.add_messages) instead.
     pub fn add_resource(&mut self, res: FluentResource) -> Result<(), Vec<FluentError>> {
         let mut errors = vec![];
 
@@ -150,6 +257,48 @@ impl<'bundle> FluentBundle<'bundle> {
         }
     }
 
+    /// Formats the message value identified by `path` using `args`.
+    /// `path` is either a message id ("hello"), or message id plus
+    /// attribute ("hello.tooltip").
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use fluent::bundle::FluentBundle;
+    /// use fluent::types::FluentValue;
+    /// use std::collections::HashMap;
+    ///
+    /// let mut bundle = FluentBundle::new(&["en-US"]);
+    /// bundle.add_messages("intro = Welcome, { $name }.");
+    ///
+    /// let mut args = HashMap::new();
+    /// args.insert("name", FluentValue::from("John"));
+    ///
+    /// let value = bundle.format("intro", Some(&args));
+    /// assert_eq!(value, Some(("Welcome, John.".to_string(), vec![])));
+    ///
+    /// ```
+    ///
+    /// An example with attributes and no args:
+    ///
+    /// ```
+    /// use fluent::bundle::FluentBundle;
+    ///
+    /// let mut bundle = FluentBundle::new(&["en-US"]);
+    /// bundle.add_messages("
+    /// hello =
+    ///     .title = Hi!
+    ///     .tooltip = This says 'Hi!'
+    /// ");
+    ///
+    /// let value = bundle.format("hello.title", None);
+    /// assert_eq!(value, Some(("Hi!".to_string(), vec![])));
+    /// ```
+    ///
+    /// # Errors
+    ///
+    /// On error, the string returned will be the path. This allows
+    /// for slightly graceful fallback during errors.
     pub fn format(
         &self,
         path: &str,
@@ -203,6 +352,7 @@ impl<'bundle> FluentBundle<'bundle> {
         None
     }
 
+    /// Use [`format`](./struct.FluentBundle.html#method.format) instead.
     pub fn format_message(
         &self,
         message_id: &str,