Add docs for mdx expressions

1 files changed, 80 insertions, 4 deletions

diff --git a/src/construct/partial_mdx_expression.rs b/src/construct/partial_mdx_expression.rs
index aeea52e..31a9af8 100644
--- a/src/construct/partial_mdx_expression.rs
+++ b/src/construct/partial_mdx_expression.rs
@@ -1,4 +1,61 @@
-//! To do.
+//! MDX expression occurs in [MDX expression (flow)][mdx_expression_flow] and
+//! [MDX expression (text)][mdx_expression_text].
+//!
+//! ## Grammar
+//!
+//! MDX expression forms with the following BNF
+//! (<small>see [construct][crate::construct] for character groups</small>):
+//!
+//! ```bnf
+//! mdx_expression ::= '{' *(expression_text | expression) '}'
+//! expression_text ::= char - '{' - '}'
+//! ```
+//!
+//! ## Tokens
+//!
+//! *   [`LineEnding`][Name::LineEnding]
+//! *   [`SpaceOrTab`][Name::SpaceOrTab]
+//! *   [`MdxExpressionMarker`][Name::MdxExpressionMarker]
+//! *   [`MdxExpressionData`][Name::MdxExpressionData]
+//!
+//! ## Recommendation
+//!
+//! When authoring markdown with JavaScript, keep in mind that MDX is a
+//! whitespace sensitive and line-based language, while JavaScript is
+//! insensitive to whitespace.
+//! This affects how markdown and JavaScript interleave with eachother in MDX.
+//! For more info on how it works, see [§ Interleaving][interleaving] on the
+//! MDX site.
+//!
+//! ## Errors
+//!
+//! ### Unexpected end of file in expression, expected a corresponding closing brace for `{`
+//!
+//! This error occurs if a `{` was seen without a `}`.
+//! For example:
+//!
+//! ```markdown
+//! a { b
+//! ```
+//!
+//! ### Unexpected lazy line in expression in container, expected line to be prefixed with `>` when in a block quote, whitespace when in a list, etc
+//!
+//! This error occurs if a a lazy line (of a container) is found in an expression.
+//! For example:
+//!
+//! ```markdown
+//! > {a +
+//! b}
+//! ```
+//!
+//! ## References
+//!
+//! *   [`micromark-factory-mdx-expression`](https://github.com/micromark/micromark-extension-mdx-expression/blob/main/packages/micromark-factory-mdx-expression/dev/index.js)
+//! *   [`mdxjs.com`](https://mdxjs.com)
+//!
+//! [mdx_expression_flow]: crate::construct::mdx_expression_flow
+//! [mdx_expression_text]: crate::construct::mdx_expression_text
+//! [interleaving]: https://mdxjs.com/docs/what-is-mdx/#interleaving
 
 use crate::construct::partial_space_or_tab::space_or_tab_min_max;
 use crate::event::Name;
@@ -6,7 +63,7 @@ use crate::state::{Name as StateName, State};
 use crate::tokenizer::Tokenizer;
 use alloc::format;
 
-/// Start of MDX: expression.
+/// Start of an MDX expression.
 ///
 /// ```markdown
 /// > | a {Math.PI} c
@@ -21,6 +78,12 @@ pub fn start(tokenizer: &mut Tokenizer) -> State {
     State::Next(StateName::MdxExpressionBefore)
 }
 
+/// Before data.
+///
+/// ```markdown
+/// > | a {Math.PI} c
+///        ^
+/// ```
 pub fn before(tokenizer: &mut Tokenizer) -> State {
     match tokenizer.current {
         None => {
@@ -38,7 +101,7 @@ pub fn before(tokenizer: &mut Tokenizer) -> State {
         Some(b'}') if tokenizer.tokenize_state.size == 0 => {
             if tokenizer.tokenize_state.token_1 == Name::MdxJsxTagAttributeValueExpression && !tokenizer.tokenize_state.seen {
                 State::Error(format!(
-                    "{}:{}: Unexpected empty in expression, expected a value between braces",
+                    "{}:{}: Unexpected empty expression, expected a value between braces",
                     tokenizer.point.line, tokenizer.point.column
                 ))
             } else {
@@ -58,6 +121,12 @@ pub fn before(tokenizer: &mut Tokenizer) -> State {
     }
 }
 
+/// In data.
+///
+/// ```markdown
+/// > | a {Math.PI} c
+///        ^
+/// ```
 pub fn inside(tokenizer: &mut Tokenizer) -> State {
     if matches!(tokenizer.current, None | Some(b'\n'))
         || (tokenizer.current == Some(b'}') && tokenizer.tokenize_state.size == 0)
@@ -77,8 +146,15 @@ pub fn inside(tokenizer: &mut Tokenizer) -> State {
     }
 }
 
+/// After eol.
+///
+/// ```markdown
+///   | a {b +
+/// > | c} d
+///     ^
+/// ```
 pub fn eol_after(tokenizer: &mut Tokenizer) -> State {
-    // Lazy continuation in a flow expression (or in a flow tag) is a syntax error.
+    // Lazy continuation in a flow expression (or flow tag) is a syntax error.
     if (tokenizer.tokenize_state.token_1 == Name::MdxFlowExpression
         || tokenizer.tokenize_state.token_2 == Name::MdxJsxFlowTag)
         && tokenizer.lazy