improve documentation

CHANGELOG.md

@@ -1,3 +1,10 @@
+# 0.9.5
+
+A small release fixing potential build issues and improving documentation.
+
+This release is not published to NPM due to [a bug](https://github.com/rustwasm/wasm-pack/issues/837)
+in `wasm-pack`.
+
 # 0.9.4
 
 - implement `@keyframes`

README.md

@@ -18,14 +18,6 @@ a bug except for in the following situations:
 [Documentation](https://docs.rs/grass/)  
 [crates.io](https://crates.io/crates/grass)
 
-## Web Assembly
-
-`grass` experimentally releases a
-[WASM version of the library to npm](https://www.npmjs.com/package/@connorskees/grass),
-compiled using wasm-bindgen. To use `grass` in your JavaScript projects, just run
-`npm install @connorskees/grass` to your package.json. Better documentation
-for this version will be provided when the library becomes more stable.
-
 ## Status
 
 The large features remaining are
@@ -34,10 +26,22 @@ The large features remaining are
 indented syntax
 css imports
 @use, @forward, and the module system
+compressed output
 ```
 
 This is in addition to dozens of smaller features, edge cases, and miscompilations.
-Features currently blocking Bootstrap are tracked [here](https://github.com/connorskees/grass/issues/4).
+
+Starting from `grass v0.9.4`, it is possible to compile Twitter Bootstrap 4 as well as bulma-scss.
+
+The output is not exact byte-for-byte, and the remaining differences in output are tracked [here](https://github.com/connorskees/grass/issues/4).
+
+## Web Assembly
+
+`grass` experimentally releases a
+[WASM version of the library to npm](https://www.npmjs.com/package/@connorskees/grass),
+compiled using wasm-bindgen. To use `grass` in your JavaScript projects, just run
+`npm install @connorskees/grass` to your package.json. Better documentation
+for this version will be provided when the library becomes more stable.
 
 ## Features
 

src/error.rs

@@ -10,6 +10,27 @@ use codemap::{Span, SpanLoc};
 
 pub type SassResult<T> = Result<T, Box<SassError>>;
 
+/// `SassError`s can be either a structured error
+/// specific to `grass` or an `io::Error`.
+///
+/// In the former case, the best way to interact with
+/// the error is to simply print it to the user. The
+/// `Display` implementation of this kind of error
+/// mirrors that of the errors `dart-sass` emits, e.g.
+///```scss
+/// Error: $number: foo is not a number.
+///     |
+/// 308 |     color: unit(foo);
+///     |                 ^^^
+///     |
+/// ./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,

src/lib.rs

@@ -124,7 +124,7 @@ fn raw_to_parse_error(map: &CodeMap, err: Error) -> Box<Error> {
     Box::new(Error::from_loc(message, map.look_up_span(span)))
 }
 
-/// Write CSS to `buf`, constructed from a path
+/// Compile CSS from a path
 ///
 /// ```
 /// fn main() -> Result<(), Box<grass::Error>> {
@@ -132,6 +132,7 @@ fn raw_to_parse_error(map: &CodeMap, err: Error) -> Box<Error> {
 ///     Ok(())
 /// }
 /// ```
+/// (grass does not currently allow files or paths that are not valid UTF-8)
 #[cfg_attr(feature = "profiling", inline(never))]
 #[cfg_attr(not(feature = "profiling"), inline)]
 #[cfg(not(feature = "wasm"))]
@@ -166,7 +167,7 @@ pub fn from_path(p: &str) -> Result<String> {
         .map_err(|e| raw_to_parse_error(&map, *e))
 }
 
-/// Write CSS to `buf`, constructed from a string
+/// Compile CSS from a string
 ///
 /// ```
 /// fn main() -> Result<(), Box<grass::Error>> {