Remaining docs

Author: devongovett

src/bundler.rs

@@ -1,3 +1,28 @@
+//! CSS bundling.
+//!
+//! A [Bundler](Bundler) can be used to combine a CSS file and all of its dependencies
+//! into a single merged style sheet. It works together with a [SourceProvider](SourceProvider)
+//! (e.g. [FileProvider](FileProvider)) to read files from the file system or another source,
+//! and returns a [StyleSheet](super::stylesheet::StyleSheet) containing the rules from all
+//! of the dependencies of the entry file, recursively.
+//!
+//! Rules are bundled following `@import` order, and wrapped in the necessary `@media`, `@supports`,
+//! and `@layer` rules as appropriate to preserve the authored behavior.
+//!
+//! # Example
+//!
+//! ```no_run
+//! use std::path::Path;
+//! use parcel_css::{
+//!   bundler::{Bundler, FileProvider},
+//!   stylesheet::ParserOptions
+//! };
+//!
+//! let fs = FileProvider::new();
+//! let mut bundler = Bundler::new(&fs, None, ParserOptions::default());
+//! let stylesheet = bundler.bundle(Path::new("style.css")).unwrap();
+//! ```
+
 use crate::{
   error::ErrorLocation,
   rules::{
@@ -27,6 +52,8 @@ use std::{
   sync::Mutex,
 };
 
+/// A Bundler combines a CSS file and all imported dependencies together into
+/// a single merged style sheet.
 pub struct Bundler<'a, 's, P> {
   source_map: Option<Mutex<&'s mut SourceMap>>,
   fs: &'a P,
@@ -47,15 +74,23 @@ struct BundleStyleSheet<'i> {
   loc: Location,
 }
 
+/// A trait to provide the contents of files to a Bundler.
+///
+/// See [FileProvider](FileProvider) for an implementation that uses the
+/// file system.
 pub trait SourceProvider: Send + Sync {
+  /// Reads the contents of the given file path to a string.
   fn read<'a>(&'a self, file: &Path) -> std::io::Result<&'a str>;
 }
 
+/// Provides an implementation of [SourceProvider](SourceProvider)
+/// that reads files from the file system.
 pub struct FileProvider {
   inputs: Mutex<Vec<*mut String>>,
 }
 
 impl FileProvider {
+  /// Creates a new FileProvider.
   pub fn new() -> FileProvider {
     FileProvider {
       inputs: Mutex::new(Vec::new()),
@@ -86,12 +121,18 @@ impl Drop for FileProvider {
   }
 }
 
+/// An error that could occur during bundling.
 #[derive(Debug, Serialize)]
 pub enum BundleErrorKind<'i> {
+  /// An I/O error occurred.
   IOError(#[serde(skip)] std::io::Error),
+  /// A parser error occurred.
   ParserError(ParserError<'i>),
+  /// An unsupported `@import` condition was encountered.
   UnsupportedImportCondition,
+  /// An unsupported cascade layer combination was encountered.
   UnsupportedLayerCombination,
+  /// Unsupported media query boolean logic was encountered.
   UnsupportedMediaBooleanLogic,
 }
 
@@ -119,12 +160,16 @@ impl<'i> std::fmt::Display for BundleErrorKind<'i> {
 
 impl<'i> BundleErrorKind<'i> {
   #[deprecated(note = "use `BundleErrorKind::to_string()` or `std::fmt::Display` instead")]
+  #[allow(missing_docs)]
   pub fn reason(&self) -> String {
     self.to_string()
   }
 }
 
 impl<'a, 's, P: SourceProvider> Bundler<'a, 's, P> {
+  /// Creates a new Bundler using the given source provider.
+  /// If a source map is given, the content of each source file included in the bundle will
+  /// be added accordingly.
   pub fn new(fs: &'a P, source_map: Option<&'s mut SourceMap>, options: ParserOptions) -> Self {
     Bundler {
       source_map: source_map.map(Mutex::new),
@@ -135,6 +180,7 @@ impl<'a, 's, P: SourceProvider> Bundler<'a, 's, P> {
     }
   }
 
+  /// Bundles the given entry file and all dependencies into a single style sheet.
   pub fn bundle<'e>(&mut self, entry: &'e Path) -> Result<StyleSheet<'a>, Error<BundleErrorKind<'a>>> {
     // Phase 1: load and parse all files. This is done in parallel.
     self.load_file(
@@ -193,7 +239,7 @@ impl<'a, 's, P: SourceProvider> Bundler<'a, 's, P> {
         {
           return Err(Error {
             kind: BundleErrorKind::UnsupportedImportCondition,
-            loc: Some(ErrorLocation::from(rule.loc, self.find_filename(rule.loc.source_index))),
+            loc: Some(ErrorLocation::new(rule.loc, self.find_filename(rule.loc.source_index))),
           });
         }
 
@@ -217,7 +263,7 @@ impl<'a, 's, P: SourceProvider> Bundler<'a, 's, P> {
             if layer != existing_layer || (layer.is_none() && existing_layer.is_none()) {
               return Err(Error {
                 kind: BundleErrorKind::UnsupportedLayerCombination,
-                loc: Some(ErrorLocation::from(rule.loc, self.find_filename(rule.loc.source_index))),
+                loc: Some(ErrorLocation::new(rule.loc, self.find_filename(rule.loc.source_index))),
               });
             }
           } else {
@@ -250,7 +296,7 @@ impl<'a, 's, P: SourceProvider> Bundler<'a, 's, P> {
 
     let code = self.fs.read(file).map_err(|e| Error {
       kind: BundleErrorKind::IOError(e),
-      loc: Some(ErrorLocation::from(rule.loc, self.find_filename(rule.loc.source_index))),
+      loc: Some(ErrorLocation::new(rule.loc, self.find_filename(rule.loc.source_index))),
     })?;
 
     let mut opts = self.options.clone();
@@ -288,7 +334,7 @@ impl<'a, 's, P: SourceProvider> Bundler<'a, 's, P> {
           let mut media = rule.media.clone();
           let result = media.and(&import.media).map_err(|_| Error {
             kind: BundleErrorKind::UnsupportedMediaBooleanLogic,
-            loc: Some(ErrorLocation::from(
+            loc: Some(ErrorLocation::new(
               import.loc,
               self.find_filename(import.loc.source_index),
             )),
@@ -304,7 +350,7 @@ impl<'a, 's, P: SourceProvider> Bundler<'a, 's, P> {
             // Cannot combine anonymous layers
             return Some(Err(Error {
               kind: BundleErrorKind::UnsupportedLayerCombination,
-              loc: Some(ErrorLocation::from(
+              loc: Some(ErrorLocation::new(
                 import.loc,
                 self.find_filename(import.loc.source_index),
               )),

src/css_modules.rs

@@ -1,3 +1,13 @@
+//! CSS module exports.
+//!
+//! [CSS modules](https://github.com/css-modules/css-modules) are a way of locally scoping names in a
+//! CSS file. This includes class names, ids, keyframe animation names, and any other places where the
+//! [CustomIdent](super::values::ident::CustomIdent) type is used.
+//!
+//! CSS modules can be enabled using the `css_modules` option when parsing a style sheet. When the
+//! style sheet is printed, hashes will be added to any declared names, and references to those names
+//! will be updated accordingly. A map of the original names to compiled (hashed) names will be returned.
+
 use crate::error::PrinterErrorKind;
 use crate::properties::css_modules::{Composes, ComposesFrom};
 use crate::selector::Selectors;
@@ -9,22 +19,44 @@ use std::collections::hash_map::DefaultHasher;
 use std::collections::HashMap;
 use std::hash::{Hash, Hasher};
 
+/// A referenced name within a CSS module, e.g. via the `composes` property.
+///
+/// See [CssModuleExport](CssModuleExport).
 #[derive(PartialEq, Debug, Clone, Serialize)]
 #[serde(tag = "type", rename_all = "lowercase")]
 pub enum CssModuleReference {
-  Local { name: String },
-  Global { name: String },
-  Dependency { name: String, specifier: String },
+  /// A local reference.
+  Local {
+    /// The local (compiled) name for the reference.
+    name: String,
+  },
+  /// A global reference.
+  Global {
+    /// The referenced global name.
+    name: String,
+  },
+  /// A reference to an export in a different file.
+  Dependency {
+    /// The name to reference within the dependency.
+    name: String,
+    /// The dependency specifier for the referenced file.
+    specifier: String,
+  },
 }
 
+/// An exported value from a CSS module.
 #[derive(PartialEq, Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CssModuleExport {
+  /// The local (compiled) name for this export.
   pub name: String,
+  /// Other names that are composed by this export.
   pub composes: Vec<CssModuleReference>,
+  /// Whether the export is referenced in this file.
   pub is_referenced: bool,
 }
 
+/// A map of exported names to values.
 pub type CssModuleExports = HashMap<String, CssModuleExport>;
 
 lazy_static! {

src/declaration.rs

@@ -1,3 +1,5 @@
+//! CSS declarations.
+
 use crate::context::PropertyHandlerContext;
 use crate::error::{ParserError, PrinterError};
 use crate::parser::ParserOptions;
@@ -29,13 +31,21 @@ use crate::targets::Browsers;
 use crate::traits::{PropertyHandler, ToCss};
 use cssparser::*;
 
+/// A CSS declaration block.
+///
+/// Properties are separated into a list of `!important` declararations,
+/// and a list of normal declarations. This reduces memory usage compared
+/// with storing a boolean along with each property.
 #[derive(Debug, PartialEq, Clone)]
 pub struct DeclarationBlock<'i> {
+  /// A list of `!important` declarations in the block.
   pub important_declarations: Vec<Property<'i>>,
+  /// A list of normal declarations in the block.
   pub declarations: Vec<Property<'i>>,
 }
 
 impl<'i> DeclarationBlock<'i> {
+  /// Parses a declaration block from CSS syntax.
   pub fn parse<'t>(
     input: &mut Parser<'i, 't>,
     options: &ParserOptions,
@@ -126,6 +136,7 @@ impl<'i> DeclarationBlock<'i> {
     self.declarations = std::mem::take(&mut handler.decls);
   }
 
+  /// Returns whether the declaration block is empty.
   pub fn is_empty(&self) -> bool {
     return self.declarations.is_empty() && self.important_declarations.is_empty();
   }

src/dependencies.rs

@@ -1,3 +1,13 @@
+//! Dependency analysis.
+//!
+//! Dependencies in CSS can be analyzed using the `analyze_dependencies` option
+//! when printing a style sheet. These include other style sheets referenved via
+//! the `@import` rule, as well as `url()` references. See [PrinterOptions](PrinterOptions).
+//!
+//! When dependency analysis is enabled, `@import` rules are removed, and `url()`
+//! dependencies are replaced with hashed placeholders that can be substituted with
+//! the final urls later (e.g. after bundling and content hashing).
+
 use crate::css_modules::hash;
 use crate::printer::PrinterOptions;
 use crate::rules::import::ImportRule;
@@ -6,22 +16,31 @@ use crate::values::url::Url;
 use cssparser::SourceLocation;
 use serde::Serialize;
 
+/// A dependency.
 #[derive(Serialize)]
 #[serde(tag = "type", rename_all = "lowercase")]
 pub enum Dependency {
+  /// An `@import` dependency.
   Import(ImportDependency),
+  /// A `url()` dependency.
   Url(UrlDependency),
 }
 
+/// An `@import` dependency.
 #[derive(Serialize)]
 pub struct ImportDependency {
+  /// The url to import.
   pub url: String,
+  /// An optional `supports()` condition.
   pub supports: Option<String>,
+  /// A media query.
   pub media: Option<String>,
+  /// The location of the dependency in the source file.
   pub loc: SourceRange,
 }
 
 impl ImportDependency {
+  /// Creates a new dependency from an `@import` rule.
   pub fn new(rule: &ImportRule, filename: &str) -> ImportDependency {
     let supports = if let Some(supports) = &rule.supports {
       let s = supports.to_css_string(PrinterOptions::default()).unwrap();
@@ -54,14 +73,19 @@ impl ImportDependency {
   }
 }
 
+/// A `url()` dependency.
 #[derive(Serialize)]
 pub struct UrlDependency {
+  /// The url of the dependency.
   pub url: String,
+  /// The placeholder that the URL was replaced with.
   pub placeholder: String,
+  /// The location of the dependency in the source file.
   pub loc: SourceRange,
 }
 
 impl UrlDependency {
+  /// Creates a new url dependency.
   pub fn new(url: &Url, filename: &str) -> UrlDependency {
     let placeholder = hash(&format!("{}_{}", filename, url.url));
     UrlDependency {
@@ -72,17 +96,24 @@ impl UrlDependency {
   }
 }
 
+/// Represents the range of source code where a dependency was found.
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SourceRange {
+  /// The filename in which the dependency was found.
   pub file_path: String,
+  /// The starting line and column position of the dependency.
   pub start: Location,
+  /// THe ending line and column position of the dependency.
   pub end: Location,
 }
 
+/// A line and column position within a source file.
 #[derive(Serialize)]
 pub struct Location {
+  /// The line number, starting from 0.
   pub line: u32,
+  /// The column number, starting from 1.
   pub column: u32,
 }