update docs

src/error.rs

@@ -10,13 +10,12 @@ use codemap::{Span, SpanLoc};
 
 pub type SassResult<T> = Result<T, Box<SassError>>;
 
-/// `SassError`s can be either a structured error
+/// `SassError`s can be either a structured error specific to `grass` or an
-/// specific to `grass` or an `io::Error`.
+/// `io::Error`.
 ///
-/// In the former case, the best way to interact with
+/// In the former case, the best way to interact with the error is to simply print
-/// the error is to simply print it to the user. The
+/// it to the user. The `Display` implementation of this kind of error mirrors
-/// `Display` implementation of this kind of error
+/// that of the errors `dart-sass` emits, e.g.
-/// mirrors that of the errors `dart-sass` emits, e.g.
 ///```scss
 /// Error: $number: foo is not a number.
 ///     |
@@ -26,11 +25,6 @@ pub type SassResult<T> = Result<T, Box<SassError>>;
 /// ./input.scss:308:17
 ///```
 ///
-/// The file name, line number, and column are structured in
-/// such a way as to allow Visual Studio Code users to go
-/// directly to the error by simply clicking the file name.
-///
-/// Note that this is a deviation from the Sass specification.
 #[derive(Debug, Clone)]
 pub struct SassError {
     kind: SassErrorKind,
@@ -77,11 +71,31 @@ impl SassError {
 #[derive(Debug, Clone)]
 pub enum PublicSassErrorKind {
     ParseError {
+        /// The message related to this parse error.
+        ///
+        /// Error messages should only be used to assist in debugging for the
+        /// end user. They may change significantly between bugfix versions and
+        /// should not be relied on to remain stable.
+        ///
+        /// Error messages do not contain the `Error: ` prefix or pretty-printed
+        /// span and context information as is shown in the `Display` implementation.
         message: String,
         loc: SpanLoc,
+
+        /// Whether or not the user allows unicode characters to be emitted in
+        /// error messages.
+        ///
+        /// This is configurable with [`crate::Options::unicode_error_messages`]
         unicode: bool,
     },
+
+    /// Sass was unable to find the entry-point file.
+    ///
+    /// Files that cannot be found using `@import`, `@use`, and `@forward` will
+    /// emit [`Self::ParseError`]s
     IoError(Arc<io::Error>),
+
+    /// The entry-point file or an imported file was not valid UTF-8.
     FromUtf8Error(String),
 }
 

src/lib.rs

@@ -1,6 +1,17 @@
 /*!
 This crate provides functionality for compiling [Sass](https://sass-lang.com/) to CSS.
 
+This crate targets compatability with the reference implementation in Dart. If
+upgrading from the [now deprecated](https://sass-lang.com/blog/libsass-is-deprecated)
+`libsass`, one may have to modify their stylesheets. These changes will not differ
+from those necessary to upgrade to `dart-sass`, and in general such changes should
+be quite rare.
+
+This crate is capable of compiling Bootstrap 4 and 5, bulma and bulma-scss, Bourbon,
+as well as most other large Sass libraries with complete accuracy. For the vast
+majority of use cases there should be no perceptible differences from the reference
+implementation.
+
 ## Use as library
 ```
 fn main() -> Result<(), Box<grass::Error>> {

src/options.rs

@@ -160,7 +160,7 @@ impl<'a> Options<'a> {
 ///
 /// See [`Options::input_syntax`] for additional information
 #[non_exhaustive]
-#[derive(Clone, Copy, Debug)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub enum InputSyntax {
     /// The CSS-superset SCSS syntax.
     Scss,
@@ -183,7 +183,7 @@ impl InputSyntax {
 }
 
 #[non_exhaustive]
-#[derive(Clone, Copy, Debug)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub enum OutputStyle {
     /// This mode writes each selector and declaration on its own line.
     ///

src/value/sass_function.rs

@@ -1,31 +1,25 @@
-//! Sass functions are those that are evaluated and return a value
-//!
-//! Sass functions can be either user-defined or builtin.
-//!
-//! User-defined functions are those that have been implemented in Sass
-//! using the @function rule. See the documentation of [`crate::atrule::Function`]
-//! for more information.
-//!
-//! Builtin functions are those that have been implemented in rust and are
-//! in the global scope.
-
 use std::{fmt, sync::Arc};
 
 use crate::{ast::AstFunctionDecl, builtin::Builtin, common::Identifier, evaluate::Environment};
 
 /// A Sass function
 ///
-/// See toplevel documentation for more information
-///
 /// The function name is stored in addition to the body
 /// for use in the builtin function `inspect()`
 #[derive(Clone, Eq, PartialEq)]
 pub(crate) enum SassFunction {
     // todo: Cow<'static>?
+    /// Builtin functions are those that have been implemented in Rust and are
+    /// in the global scope.
     Builtin(Builtin, Identifier),
+
     // todo: maybe arc?
+    /// User-defined functions are those that have been implemented in Sass using
+    /// the @function rule.
     UserDefined(UserDefinedFunction),
-    Plain { name: Identifier },
+    Plain {
+        name: Identifier,
+    },
 }
 
 #[derive(Debug, Clone)]