docs: Document parse module

Author: Stranger6667

src/lib.rs

@@ -126,24 +126,23 @@
     unused_qualifications,
     variant_size_differences
 )]
-use crate::parse::Declaration;
 use kuchiki::traits::TendrilSink;
 use kuchiki::{parse_html, Selectors};
 
 pub mod error;
-mod parse;
+mod parser;
 
 pub use error::InlineError;
 use std::collections::HashMap;
 
 #[derive(Debug)]
 struct Rule {
     selectors: Selectors,
-    declarations: Vec<Declaration>,
+    declarations: Vec<parser::Declaration>,
 }
 
 impl Rule {
-    pub fn new(selectors: &str, declarations: Vec<Declaration>) -> Result<Rule, ()> {
+    pub fn new(selectors: &str, declarations: Vec<parser::Declaration>) -> Result<Rule, ()> {
         Ok(Rule {
             selectors: Selectors::compile(selectors)?,
             declarations,
@@ -211,7 +210,7 @@ impl CSSInliner {
                 if let Some(css_cell) = first_child.as_text() {
                     let css = css_cell.borrow();
                     let mut parse_input = cssparser::ParserInput::new(css.as_str());
-                    let mut parser = parse::CSSParser::new(&mut parse_input);
+                    let mut parser = parser::CSSParser::new(&mut parse_input);
                     for parsed in parser.parse() {
                         if let Ok((selector, declarations)) = parsed {
                             let rule = Rule::new(&selector, declarations).map_err(|_| {
@@ -262,12 +261,15 @@ pub fn inline(html: &str) -> Result<String, InlineError> {
     CSSInliner::default().inline(html)
 }
 
-fn merge_styles(existing_style: &str, new_styles: &[Declaration]) -> Result<String, InlineError> {
+fn merge_styles(
+    existing_style: &str,
+    new_styles: &[parser::Declaration],
+) -> Result<String, InlineError> {
     // Parse existing declarations in "style" attribute
     let mut input = cssparser::ParserInput::new(existing_style);
     let mut parser = cssparser::Parser::new(&mut input);
     let declarations =
-        cssparser::DeclarationListParser::new(&mut parser, parse::CSSDeclarationListParser);
+        cssparser::DeclarationListParser::new(&mut parser, parser::CSSDeclarationListParser);
     // Merge existing with the new ones
     // We know that at least one rule already exists, so we add 1
     let mut styles: HashMap<String, String> =

src/parse.rs renamed to src/parser.rs

@@ -10,6 +10,9 @@ fn exhaust(input: &mut cssparser::Parser) -> String {
     input.slice_from(start).to_string()
 }
 
+/// Parser for qualified rules - a prelude + a simple {} block.
+///
+/// Usually these rules are a selector + list of declarations: `p { color: blue; font-size: 2px }`
 impl<'i> cssparser::QualifiedRuleParser<'i> for CSSRuleListParser {
     type Prelude = String;
     type QualifiedRule = QualifiedRule;
@@ -19,6 +22,7 @@ impl<'i> cssparser::QualifiedRuleParser<'i> for CSSRuleListParser {
         &mut self,
         input: &mut cssparser::Parser<'i, 't>,
     ) -> Result<Self::Prelude, cssparser::ParseError<'i, Self::Error>> {
+        // Proceed with parsing until the end of the prelude.
         Ok(exhaust(input))
     }
 
@@ -28,6 +32,7 @@ impl<'i> cssparser::QualifiedRuleParser<'i> for CSSRuleListParser {
         _: cssparser::SourceLocation,
         input: &mut cssparser::Parser<'i, 't>,
     ) -> Result<Self::QualifiedRule, cssparser::ParseError<'i, Self::Error>> {
+        // Parse list of declarations
         let parser = cssparser::DeclarationListParser::new(input, CSSDeclarationListParser);
         let mut declarations = vec![];
 
@@ -41,6 +46,7 @@ impl<'i> cssparser::QualifiedRuleParser<'i> for CSSRuleListParser {
     }
 }
 
+/// Parse a declaration within {} block: `color: blue`
 impl<'i> cssparser::DeclarationParser<'i> for CSSDeclarationListParser {
     type Declaration = Declaration;
     type Error = ();
@@ -61,6 +67,8 @@ impl cssparser::AtRuleParser<'_> for CSSRuleListParser {
     type Error = ();
 }
 
+/// Parsing for at-rules, e.g: `@charset "utf-8";`
+/// Since they are can not be inlined we use the default implementation, that rejects all at-rules.
 impl cssparser::AtRuleParser<'_> for CSSDeclarationListParser {
     type PreludeNoBlock = String;
     type PreludeBlock = String;