diff --git a/src/lib.rs b/src/lib.rs index 2e56b76..1234886 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -125,10 +125,20 @@ mod value; #[non_exhaustive] #[derive(Debug)] pub enum OutputStyle { + /// The default style, this mode writes each + /// selector and declaration on its own line. Expanded, + /// Ideal for release builds, this mode removes + /// as many extra characters as possible and + /// writes the entire stylesheet on a single line. Compressed, } +/// Configuration for Sass compilation +/// +/// The simplest usage is `grass::Options::default()`; +/// however, a builder pattern is also exposed to offer +/// more control. #[derive(Debug)] pub struct Options<'a> { style: OutputStyle, @@ -156,7 +166,7 @@ impl<'a> Options<'a> { /// `grass` currently offers 2 different output styles /// /// - `OutputStyle::Expanded` writes each selector and declaration on its own line. - /// - `OutputStyle::Compressed` removes as many extra characters as possible, + /// - `OutputStyle::Compressed` removes as many extra characters as possible /// and writes the entire stylesheet on a single line. /// /// By default, output is expanded. @@ -181,9 +191,19 @@ impl<'a> Options<'a> { self } - /// `load_paths` - list of paths/files to check for imports for more information see the docs: - /// - - /// - + /// All Sass implementations allow users to provide + /// load paths: paths on the filesystem that Sass + /// will look in when locating modules. For example, + /// if you pass `node_modules/susy/sass` as a load path, + /// you can use `@import "susy"` to load `node_modules/susy/sass/susy.scss`. + /// + /// Imports will always be resolved relative to the current + /// file first, though. Load paths will only be used if no + /// relative file exists that matches the module's URL. This + /// ensures that you can't accidentally mess up your relative + /// imports when you add a new library. + /// + /// This method will append a single path to the list. #[must_use] #[inline] pub fn load_path(mut self, path: &'a Path) -> Self { @@ -191,7 +211,11 @@ impl<'a> Options<'a> { self } - /// adds on to the `load_path` vec, does not set the vec to paths + /// Append multiple loads paths + /// + /// Note that this method does *not* remove existing load paths + /// + /// See [`Options::load_path`](Options::load_path) for more information about load paths #[must_use] #[inline] pub fn load_paths(mut self, paths: &'a [&'a Path]) -> Self { @@ -199,6 +223,13 @@ impl<'a> Options<'a> { self } + /// This flag tells Sass whether to emit a `@charset` + /// declaration or a UTF-8 byte-order mark. + /// + /// By default, Sass will insert either a `@charset` + /// declaration (in expanded output mode) or a byte-order + /// mark (in compressed output mode) if the stylesheet + /// contains any non-ASCII characters. #[must_use] #[inline] pub fn allows_charset(mut self, allows_charset: bool) -> Self { @@ -206,6 +237,13 @@ impl<'a> Options<'a> { self } + /// This flag tells Sass only to emit ASCII characters as + /// part of error messages. + /// + /// By default Sass will emit non-ASCII characters for + /// these messages. + /// + /// This flag does not affect the CSS output. #[must_use] #[inline] pub fn unicode_error_messages(mut self, unicode_error_messages: bool) -> Self {