add docs to ArgumentResolver and the type-safe messages example

Author: JasperDeSutter

fluent-bundle/examples/typesafe_messages.rs

@@ -1,3 +1,13 @@
+// This is an example of an application which adds a custom argument resolver
+// to add type safety.
+// See the external_arguments example if you are not yet familiar with fluent arguments.
+//
+// The goal is that we prevent bugs caused by mixing up arguments that belong
+// to different messages.
+// We can achieve this by defining structs for each message that encode the
+// argument types with the corresponding message ID, and then hooking into
+// fluent's resolver using a custom fluent_bundle::ArgumentResolver implementation.
+
 use std::borrow::Cow;
 
 use fluent_bundle::{ArgumentResolver, FluentBundle, FluentError, FluentResource, FluentValue};
@@ -98,13 +108,16 @@ trait Message<'a> {
     fn get_arg(&self, name: &str) -> Option<FluentValue<'a>>;
 }
 
+// by using &dyn, we prevent monomorphization for each Message struct
+// this keeps binary code size in check
 impl<'a, 'b> ArgumentResolver<'a> for &'a dyn Message<'b> {
     fn resolve(self, name: &str) -> Option<Cow<FluentValue<'a>>> {
         let arg = self.get_arg(name)?;
         Some(Cow::Owned(arg))
     }
 }
 
+// allows for method syntax, i.e. bundle.format_message(...)
 trait CustomizedBundle {
     fn format_message<'b>(
         &'b self,

fluent-bundle/src/resolver/scope.rs

@@ -146,6 +146,11 @@ impl<'bundle, 'ast, 'args, 'errors, R, M, Args: ArgumentResolver<'args>>
     }
 }
 
+/// Determines how to retrieve argument values when resolving fluent messages.
+/// This trait can be used to implement an alternative to [`FluentArgs`].
+/// 
+/// One example usage is for argument type safety that [`FluentArgs`] can't provide due to its
+/// flexible nature. See `fluent-bundle/examples/typesafe_messages.rs` for an example of this.
 pub trait ArgumentResolver<'a>: Copy {
     fn resolve(self, name: &str) -> Option<Cow<FluentValue<'a>>>;
 }