docs: add missing documentation

src/attributes.rs

@@ -1,39 +1,65 @@
+//! Global attributes of MathML elements.
+
 use std::fmt::Display;
 
 /// Direction for [`Attribute::Dir`].
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub enum Dir {
+    /// `rtl` direction.
     RightToLeft,
+    /// `ltr` direction.
     LeftToRight,
 }
 
 /// ScriptLevel for [`Attribute::ScriptLevel`].
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub enum ScriptLevel {
+    /// A positive number.
     Add(usize),
+    /// A negative number.
     Sub(usize),
+    /// A (positive) number.
     Num(usize),
 }
 
+/// MathVariant for [`Attribute::MathVariant`].
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub enum MathVariant {
+    /// Normal variant.
     Normal,
+    /// Bold variant.
     Bold,
+    /// Italic variant.
     Italic,
+    /// Bold italic variant.
     BoldItalic,
+    /// Double struck variant.
     DoubleStruck,
+    /// Bold fraktur variant.
     BoldFraktur,
+    /// Script variant.
     Script,
+    /// Bold script variant.
     BoldScript,
+    /// Fraktur variant.
     Fraktur,
+    /// Sans serif variant.
     SansSerif,
+    /// Bold sans serif variant.
     BoldSansSerif,
+    /// Sans serif italic variant.
     SansSerifItalic,
+    /// Sans serif bold italic variant.
     SansSerifBoldItalic,
+    /// Monospace variant.
     Monospace,
+    /// Initial variant.
     Initial,
+    /// Tailed variant.
     Tailed,
+    /// Looped variant.
     Looped,
+    /// Stretched variant.
     Stretched,
 }
 
@@ -121,6 +147,22 @@ pub enum Attribute {
     /// The `tabindex` attribute, same as in HTML.
     TabIndex(i16),
 
+    /// Event handler function, e.g. `onclick="..."`.
+    ///
+    /// # Example
+    /// ```rust
+    /// use alemat::{Attribute, BufMathMlWriter, Writer};
+    ///
+    /// let handler = Attribute::OnHandler {
+    ///     name: "click".to_string(),
+    ///     handler: "console.log('Clicked!')".to_string(),
+    /// };
+    ///
+    /// let mut writer = BufMathMlWriter::default();
+    /// writer.write_attr(&handler);
+    /// let output = writer.finish();
+    ///
+    /// assert_eq!(output, "onclick=\"console.log('Clicked!')\"");
     OnHandler {
         /// Name of the event.
         name: String,

src/buf_writer.rs

@@ -9,9 +9,10 @@ use crate::{
         AnnotationAttr, AnnotationContent, FracAttr, Num, OperatorAttr, PaddedAttr, SpaceAttr,
         TableAttr, TableCellAttr,
     },
-    Element, MathMlAttr, Renderer, Writer,
+    DisplayAttr, Element, MathMlAttr, Renderer, Writer,
 };
 
+/// Default implementation of MathMl [`Writer`].
 #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct BufMathMlWriter {
     buf: String,
@@ -580,7 +581,13 @@ impl Writer for BufMathMlWriter {
             self.write_str(" ")?;
 
             match attr {
-                MathMlAttr::Display(d) => write!(self, r#"display="{d}""#)?,
+                MathMlAttr::Display(d) => {
+                    write!(self, r#"display=""#)?;
+                    match d {
+                        DisplayAttr::Block => write!(self, r#"block""#)?,
+                        DisplayAttr::Inline => write!(self, r#"inline""#)?,
+                    }
+                }
                 MathMlAttr::AltText(alt_t) => write!(self, r#"alttext="{alt_t}""#)?,
                 MathMlAttr::Global(a) => self.write_attr(a)?,
             }
@@ -600,6 +607,10 @@ impl Writer for BufMathMlWriter {
     fn into_inner(self) -> Self::Buffer {
         self.buf
     }
+
+    fn finish(&mut self) -> Self::Buffer {
+        std::mem::take(&mut self.buf)
+    }
 }
 
 impl Renderer for BufMathMlWriter {

src/default_renderer.rs

@@ -8,9 +8,10 @@ use crate::{
         AnnotationAttr, AnnotationContent, FracAttr, Num, OperatorAttr, PaddedAttr, SpaceAttr,
         TableAttr, TableCellAttr,
     },
-    Element, MathMlAttr, Renderer,
+    DisplayAttr, Element, MathMlAttr, Renderer,
 };
 
+/// Default MathMl [`Renderer`] implementation.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct MathMlFormatter;
 
@@ -521,7 +522,10 @@ impl Renderer for MathMlFormatter {
             .attr
             .iter()
             .map(|a| match a {
-                MathMlAttr::Display(d) => Ok(format!(r#"display="{d}""#)),
+                MathMlAttr::Display(d) => match d {
+                    DisplayAttr::Block => Ok(String::from(r#"display="block""#)),
+                    DisplayAttr::Inline => Ok(String::from(r#"display="inline""#)),
+                },
                 MathMlAttr::AltText(alt_t) => Ok(format!(r#"alttext="{alt_t}""#)),
                 MathMlAttr::Global(a) => self.render_attr(a),
             })

src/elements.rs

@@ -2,16 +2,16 @@
 //! elements.
 
 mod maction;
-mod math;
 mod merror;
 mod mmultiscripts;
 mod mphantom;
 mod mrow;
 mod mstyle;
 
+/// The grouping elements are `maction`, `math`, `merror`, `mphantom`, `mprescripts`, `mrow`,
+/// `mstyle`, `semantics` and unknown MathML elements.
 pub mod grouping {
     pub use super::maction::*;
-    pub use super::math::*;
     pub use super::merror::*;
     pub use super::mmultiscripts::Prescripts;
     pub use super::mphantom::*;
@@ -21,13 +21,17 @@ pub mod grouping {
 
 mod mroot;
 
+/// The radical elements are `mroot` and `msqrt`. In this implementation both are constructed using
+/// the [`Radical`] struct.
 pub mod radicals {
     pub use super::mroot::*;
 }
 
 mod msubsup;
 mod munderover;
 
+/// The scripted elements are `mmultiscripts`, `mover`, `msub`, `msubsup`, `msup`, `munder` and
+/// `munderover`.
 pub mod scripted {
     pub use super::mmultiscripts::Multiscripts;
     pub use super::msubsup::*;
@@ -66,31 +70,74 @@ use self::{
     scripted::UnderOver,
 };
 
+/// The MathML elements.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub enum Element {
+    /// `maction` element.
     Action(Action),
+
+    /// `annotation` and `annotation-xml` elements.
     Annotation(Annotation),
+
+    /// `merror` element.
     Error(Error),
+
+    /// `mfrac` element.
     Frac(Frac),
+
+    /// `mi` element.
     Ident(Ident),
+
+    /// `mmultiscripts` element.
     Multiscripts(Multiscripts),
+
+    /// `mprescripts` element.
     Prescripts(Prescripts),
+
+    /// `mn` element.
     Num(Num),
+
+    /// `mo` element.
     Operator(Operator),
+
+    /// `mpadded` element.
     Padded(Padded),
+
+    /// `mphantom` element.
     Phantom(Phantom),
+
+    /// `mroot` and `msqrt` elements.
     Radical(Radical),
+
+    /// `mrow` element.
     Row(Row),
+
+    /// `msemantics` element.
     Semantics(Semantics),
+
+    /// `mspace` element.
     Space(Space),
+
+    /// `ms` element.
     StrLiteral(StrLiteral),
+
+    /// `mstyle`
     Style(Style),
+
+    /// `msub`, `msup` and `msubsup` elements.
     SubSup(SubSup),
+
+    /// `mtable` element.
     Table(Table),
+
+    /// `mtext` element.
     Text(Text),
+
+    /// `munder`, `mover` and `munderover` elements.
     UnderOver(UnderOver),
 }
 
+/// A list of [`Element`]s.
 #[repr(transparent)]
 #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct Elements(pub(crate) Vec<Element>);
@@ -109,6 +156,7 @@ impl DerefMut for Elements {
 }
 
 impl Elements {
+    /// Consumes the [`Elements`] and returns a [`Vec`] of [`Element`]s.
     pub fn into_inner(self) -> Vec<Element> {
         self.0
     }
@@ -130,6 +178,7 @@ macro_rules! children {
     }
 }
 
+/// Trait for conversion into [`Elements`].
 pub trait IntoElements {
     /// Converts the type into elements.
     fn into_elements(self) -> Elements;

src/elements/annotation.rs

@@ -11,7 +11,9 @@ use super::IntoElements;
 /// The content of `annotation` element, either text or MathML.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub enum AnnotationContent {
+    /// Text content of the `annotation` element. Implies the `annotation` variant.
     Text(String),
+    /// MathML content of the `annotation` element. Implies the `annotation-xml` variant.
     Nested(Elements),
 }
 
@@ -42,6 +44,7 @@ impl From<Element> for AnnotationContent {
 /// [`Attribute`]: crate::attributes::Attribute
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub enum AnnotationAttr {
+    /// One of the global [`Attribute`]s.
     Global(Attribute),
 
     /// NOTE: Authors can use the encoding attribute to distinguish annotations for HTML
@@ -78,19 +81,23 @@ pub struct Annotation {
 crate::element_from_type!(Annotation => Annotation);
 
 impl Annotation {
+    /// Create a builder for [`Annotation`] element.
     pub fn builder() -> AnnotationBuilder<Uninit> {
         AnnotationBuilder::default()
     }
 
+    /// Get a reference to the inner content of the [`Annotation`] element.
     pub fn content(&self) -> &AnnotationContent {
         &self.content
     }
 
+    /// Get a reference to all attributes of the [`Annotation`] element.
     pub fn attributes(&self) -> &[AnnotationAttr] {
         &self.attributes
     }
 }
 
+/// Builder of the [`Annotation`] element.
 #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct AnnotationBuilder<T> {
     content: Option<AnnotationContent>,
@@ -100,6 +107,7 @@ pub struct AnnotationBuilder<T> {
 }
 
 impl<T> AnnotationBuilder<T> {
+    /// Set the content of the [`Annotation`] element.
     pub fn content(self, content: impl Into<AnnotationContent>) -> AnnotationBuilder<Init> {
         AnnotationBuilder {
             content: Some(content.into()),
@@ -108,6 +116,7 @@ impl<T> AnnotationBuilder<T> {
         }
     }
 
+    /// Add attributes.
     pub fn attr<I, A>(mut self, attr: I) -> Self
     where
         I: IntoIterator<Item = A>,
@@ -119,6 +128,7 @@ impl<T> AnnotationBuilder<T> {
 }
 
 impl AnnotationBuilder<Init> {
+    /// Build the [`Annotation`] element.
     pub fn build(self) -> Annotation {
         Annotation {
             content: self
@@ -143,21 +153,25 @@ pub struct Semantics {
 }
 
 impl Semantics {
+    /// Create a builder for [`Semantics`] element.
     pub fn builder() -> SemanticsBuilder<Uninit> {
         SemanticsBuilder::default()
     }
 
+    /// Get a reference to the inner content of the [`Semantics`] element.
     pub fn children(&self) -> &[Element] {
         &self.children
     }
 
+    /// Get a reference to all attributes of the [`Semantics`] element.
     pub fn attributes(&self) -> &[Attribute] {
         &self.attr
     }
 }
 
 crate::element_from_type!(Semantics => Semantics);
 
+/// Builder of the [`Semantics`] element.
 #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct SemanticsBuilder<T> {
     content: Option<Elements>,
@@ -167,6 +181,7 @@ pub struct SemanticsBuilder<T> {
 }
 
 impl<T> SemanticsBuilder<T> {
+    /// Set the content of the [`Semantics`] element.
     pub fn content(self, content: impl IntoElements) -> SemanticsBuilder<Init> {
         SemanticsBuilder {
             content: Some(content.into_elements()),
@@ -175,6 +190,7 @@ impl<T> SemanticsBuilder<T> {
         }
     }
 
+    /// Add attributes.
     pub fn attr<A>(mut self, attr: A) -> Self
     where
         A: IntoIterator<Item = Attribute>,
@@ -185,6 +201,7 @@ impl<T> SemanticsBuilder<T> {
 }
 
 impl SemanticsBuilder<Init> {
+    /// Build the [`Semantics`] element.
     pub fn build(self) -> Semantics {
         Semantics {
             children: self