docs: add more

src/enclosed/parser.rs

@@ -3,6 +3,8 @@ use crate::{IntoSkipOrFatal, Parse};
 use derive_more::{Display, Error};
 use split_first_char::split_first_char;
 
+/// Parse a template string whose queries are placed between an opening bracket character and a closing bracket character,
+/// (such as [curly braces](crate::simple_curly_braces)).
 #[derive(Debug, Clone, Copy)]
 pub struct EnclosedTemplateParser<EscapeParser, QueryParser> {
     pub config: ParserConfig,
@@ -13,11 +15,13 @@ pub struct EnclosedTemplateParser<EscapeParser, QueryParser> {
 pub type Parser<EscapeParser, QueryParser> = EnclosedTemplateParser<EscapeParser, QueryParser>;
 
 impl<EscapeParser, QueryParser> Parser<EscapeParser, QueryParser> {
+    /// Replace [`Parser::config`].
     pub fn with_config(mut self, config: ParserConfig) -> Self {
         self.config = config;
         self
     }
 
+    /// Replace [`Parser::escape_parser`].
     pub fn with_escape_parser<NewEscapeParser>(
         self,
         escape_parser: NewEscapeParser,
@@ -34,6 +38,7 @@ impl<EscapeParser, QueryParser> Parser<EscapeParser, QueryParser> {
         }
     }
 
+    /// Replace [`Parser::query_parser`].
     pub fn with_query_parser<NewQueryParser>(
         self,
         query_parser: NewQueryParser,
@@ -52,6 +57,38 @@ impl<EscapeParser, QueryParser> Parser<EscapeParser, QueryParser> {
 }
 
 impl Parser<(), ()> {
+    /// Create a builder of an [`EnclosedTemplateParser`] of templates whose queries should be placed between curly braces.
+    ///
+    /// The curly braces can be replaced by [replacing the config][Parser::with_config].
+    ///
+    /// The value returned from this function is not useful immediately. The [query parser][Parser::with_query_parser] and the
+    /// [escape parser][Parser::with_escape_parser] must be replaced first.
+    ///
+    /// **Usage example:**
+    ///
+    /// ```
+    /// # #[cfg(not(feature = "std"))] fn main() {}
+    /// # #[cfg(feature = "std")] fn main() {
+    /// # use pretty_assertions::assert_eq;
+    /// use lazy_template::{
+    ///     enclosed::{Parser, SimpleEscapeParser, SimpleQuery, SimpleQueryParser},
+    ///     IntoTemplateSystem,
+    /// };
+    /// let output = Parser::curly_braces()
+    ///     .with_escape_parser(SimpleEscapeParser)
+    ///     .with_query_parser(SimpleQueryParser)
+    ///     .into_template_system::<SimpleQuery>()
+    ///     .lazy_parse("{name} is a {age} years old {gender}")
+    ///     .to_string(|query| match query {
+    ///         "name" => Ok("Alice"),
+    ///         "age" => Ok("20"),
+    ///         "gender" => Ok("girl"),
+    ///         _ => Err(format!("Can't answer {query:?}")),
+    ///     })
+    ///     .unwrap();
+    /// assert_eq!(output, "Alice is a 20 years old girl");
+    /// # }
+    /// ```
     pub fn curly_braces() -> Self {
         Parser {
             config: ParserConfig::curly_braces(),
@@ -61,6 +98,7 @@ impl Parser<(), ()> {
     }
 }
 
+/// Error type of [`Parse`] on [`EnclosedTemplateParser`].
 #[derive(Debug, Display, Error, Clone, Copy)]
 pub enum ParseError<ParseEscapeError, ParseQueryError> {
     #[display("Unexpected token {_0:?}")]