Document resolvers in the fluent-bundle

Author: gregtatum

fluent-bundle/src/resolver/errors.rs

@@ -1,6 +1,9 @@
 use fluent_syntax::ast::InlineExpression;
 use std::error::Error;
 
+/// Maps an [`InlineExpression`] into the kind of reference, with owned strings
+/// that identify the expression. This makes it so that the [`InlineExpression`] can
+/// be used to generate an error string.
 #[derive(Debug, PartialEq, Clone)]
 pub enum ReferenceKind {
     Function {
@@ -44,6 +47,8 @@ where
     }
 }
 
+/// Errors generated during the process of resolving a fluent message into a string.
+/// This process takes place in the `write` method of the `WriteValue` trait.
 #[derive(Debug, PartialEq, Clone)]
 pub enum ResolverError {
     Reference(ReferenceKind),

fluent-bundle/src/resolver/mod.rs

@@ -1,3 +1,8 @@
+//! The `resolver` module contains the definitions and implementations for the internal
+//! `ResolveValue` and `WriteValue` traits. The former converts AST nodes to a
+//! [`FluentValue`], and the latter converts them to a string that is written to an
+//! implementor of the [`std::fmt::Write`] trait.
+
 pub mod errors;
 mod expression;
 mod inline_expression;
@@ -14,8 +19,9 @@ use crate::memoizer::MemoizerKind;
 use crate::resource::FluentResource;
 use crate::types::FluentValue;
 
-// Converts an AST node to a `FluentValue`.
+/// Resolves an AST node to a [`FluentValue`].
 pub(crate) trait ResolveValue<'bundle> {
+    /// Resolves an AST node to a [`FluentValue`].
     fn resolve<'ast, 'args, 'errors, R, M>(
         &'ast self,
         scope: &mut Scope<'bundle, 'ast, 'args, 'errors, R, M>,
@@ -25,7 +31,9 @@ pub(crate) trait ResolveValue<'bundle> {
         M: MemoizerKind;
 }
 
+/// Resolves an AST node to a string that is written to source `W`.
 pub(crate) trait WriteValue<'bundle> {
+    /// Resolves an AST node to a string that is written to source `W`.
     fn write<'ast, 'args, 'errors, W, R, M>(
         &'ast self,
         w: &mut W,
@@ -36,6 +44,8 @@ pub(crate) trait WriteValue<'bundle> {
         R: Borrow<FluentResource>,
         M: MemoizerKind;
 
+    /// Writes error information to `W`. This can be used to add FTL errors inline
+    /// to a message.
     fn write_error<W>(&self, _w: &mut W) -> fmt::Result
     where
         W: fmt::Write;

fluent-bundle/src/resolver/scope.rs

@@ -49,12 +49,11 @@ impl<'bundle, 'ast, 'args, 'errors, R, M> Scope<'bundle, 'ast, 'args, 'errors, R
         }
     }
 
-    // This method allows us to lazily add Pattern on the stack,
-    // only if the Pattern::resolve has been called on an empty stack.
-    //
-    // This is the case when pattern is called from Bundle and it
-    // allows us to fast-path simple resolutions, and only use the stack
-    // for placeables.
+    /// This method allows us to lazily add Pattern on the stack, only if the
+    /// Pattern::resolve has been called on an empty stack.
+    ///
+    /// This is the case when pattern is called from Bundle and it allows us to fast-path
+    /// simple resolutions, and only use the stack for placeables.
     pub fn maybe_track<W>(
         &mut self,
         w: &mut W,