Add docs for mdx expressions

3 files changed, 152 insertions, 12 deletions

diff --git a/src/construct/mdx_expression_flow.rs b/src/construct/mdx_expression_flow.rs
index 0faea31..ef3ca41 100644
--- a/src/construct/mdx_expression_flow.rs
+++ b/src/construct/mdx_expression_flow.rs
@@ -1,4 +1,38 @@
-//! To do.
+//! MDX expression (flow) occurs in the [flow][] content type.
+//!
+//! ## Grammar
+//!
+//! MDX expression (flow) forms with the following BNF
+//! (<small>see [construct][crate::construct] for character groups</small>):
+//!
+//! ```bnf
+//! mdx_expression_flow ::= mdx_expression *space_or_tab
+//!
+//! ; See the `partial_mdx_expression` construct for the BNF of that part.
+//! ```
+//!
+//! As this construct occurs in flow, like all flow constructs, it must be
+//! followed by an eol (line ending) or eof (end of file).
+//!
+//! See [`mdx_expression`][mdx_expression] for more info.
+//!
+//! ## Tokens
+//!
+//! *   [`MdxFlowExpression`][Name::MdxFlowExpression]
+//! *   [`SpaceOrTab`][Name::SpaceOrTab]
+//! *   see [`mdx_expression`][mdx_expression] for more
+//!
+//! ## Recommendation
+//!
+//! See [`mdx_expression`][mdx_expression] for recommendations.
+//!
+//! ## References
+//!
+//! *   [`syntax.js` in `micromark-extension-mdx-expression`](https://github.com/micromark/micromark-extension-mdx-expression/blob/main/packages/micromark-extension-mdx-expression/dev/lib/syntax.js)
+//! *   [`mdxjs.com`](https://mdxjs.com)
+//!
+//! [flow]: crate::construct::flow
+//! [mdx_expression]: crate::construct::partial_mdx_expression
 
 use crate::construct::partial_space_or_tab::{space_or_tab, space_or_tab_min_max};
 use crate::event::Name;
@@ -6,7 +40,7 @@ use crate::state::{Name as StateName, State};
 use crate::tokenizer::Tokenizer;
 use crate::util::constant::TAB_SIZE;
 
-/// Start of MDX: expression (flow).
+/// Start of an MDX expression (flow).
 ///
 /// ```markdown
 /// > | {Math.PI}
@@ -35,7 +69,7 @@ pub fn start(tokenizer: &mut Tokenizer) -> State {
     }
 }
 
-/// After optional whitespace, before of MDX expression (flow).
+/// After optional whitespace, before expression.
 ///
 /// ```markdown
 /// > | {Math.PI}
@@ -50,7 +84,7 @@ pub fn before(tokenizer: &mut Tokenizer) -> State {
     }
 }
 
-/// After an MDX expression (flow).
+/// After expression.
 ///
 /// ```markdown
 /// > | {Math.PI}
@@ -66,7 +100,7 @@ pub fn after(tokenizer: &mut Tokenizer) -> State {
     }
 }
 
-/// After an MDX expression (flow), after optional whitespace.
+/// After expression, after optional whitespace.
 ///
 /// ```markdown
 /// > | {Math.PI}␠␊
diff --git a/src/construct/mdx_expression_text.rs b/src/construct/mdx_expression_text.rs
index 8d061eb..53160a0 100644
--- a/src/construct/mdx_expression_text.rs
+++ b/src/construct/mdx_expression_text.rs
@@ -1,10 +1,40 @@
-//! To do.
+//! MDX expression (text) occurs in the [text][] content type.
+//!
+//! ## Grammar
+//!
+//! MDX expression (text) forms with the following BNF
+//! (<small>see [construct][crate::construct] for character groups</small>):
+//!
+//! ```bnf
+//! mdx_expression_text ::= mdx_expression
+//!
+//! ; See the `partial_mdx_expression` construct for the BNF of that part.
+//! ```
+//!
+//! See [`mdx_expression`][mdx_expression] for more info.
+//!
+//! ## Tokens
+//!
+//! *   [`MdxTextExpression`][Name::MdxTextExpression]
+//! *   see [`mdx_expression`][mdx_expression] for more
+//!
+//! ## Recommendation
+//!
+//! See [`mdx_expression`][mdx_expression] for recommendations.
+//!
+//! ## References
+//!
+//! *   [`syntax.js` in `micromark-extension-mdx-expression`](https://github.com/micromark/micromark-extension-mdx-expression/blob/main/packages/micromark-extension-mdx-expression/dev/lib/syntax.js)
+//! *   [`mdxjs.com`](https://mdxjs.com)
+//!
+//! [text]: crate::construct::text
+//! [mdx_expression]: crate::construct::partial_mdx_expression
 
 use crate::event::Name;
 use crate::state::{Name as StateName, State};
 use crate::tokenizer::Tokenizer;
 
-/// Start of MDX: expression (text).
+/// Start of an MDX expression (text).
 ///
 /// ```markdown
 /// > | a {Math.PI} c
@@ -22,7 +52,7 @@ pub fn start(tokenizer: &mut Tokenizer) -> State {
     }
 }
 
-/// After an MDX expression (text) tag.
+/// After expression.
 ///
 /// ```markdown
 /// > | a {Math.PI} c
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