Add more documentation about Module and Backend.

lib/faerie/src/backend.rs

@@ -85,6 +85,8 @@ impl FaerieBuilder {
 }
 
 /// A `FaerieBackend` implements `Backend` and emits ".o" files using the `faerie` library.
+///
+/// See the `FaerieBuilder` for a convenient way to construct `FaerieBackend` instances.
 pub struct FaerieBackend {
     isa: Box<TargetIsa>,
     artifact: faerie::Artifact,

lib/module/README.md

@@ -1,7 +1,20 @@
-This crate provides the `Module` trait, which provides an interface for
+This crate provides module-level functionality, which allow multiple
-multiple functions and data to be emitted with
+functions and data to be emitted with
 [Cranelift](https://crates.io/crates/cranelift) and then linked together.
 
 This crate is structured as an optional layer on top of cranelift-codegen.
 It provides additional functionality, such as linking, however users that
 require greater flexibility don't need to use it.
+
+A `Module` is a collection of functions and data objects that are linked
+together. `Backend` is a trait that defines an interface for backends
+that compile modules into various forms. Most users will use one of the
+following `Backend` implementations:
+
+ - `SimpleJITBackend`, provided by [cranelift-simplejit], which JITs
+   code to memory for direct execution.
+ - `FaerieBackend`, provided by [cranelift-faerie], which emits native
+   object files.
+
+[cranelift-simplejit]: https://crates.io/crates/cranelift-simplejit
+[cranelift-faerie]: https://crates.io/crates/cranelift-faerie

lib/module/src/backend.rs

@@ -10,6 +10,15 @@ use ModuleNamespace;
 use ModuleResult;
 
 /// A `Backend` implements the functionality needed to support a `Module`.
+///
+/// Two notable implementations of this trait are:
+///  - `SimpleJITBackend`, defined in [cranelift-simplejit], which JITs
+///    the contents of a `Module` to memory which can be directly executed.
+///  - `FaerieBackend`, defined in [cranelift-faerie], which writes the
+///    contents of a `Module` out as a native object file.
+///
+/// [cranelift-simplejit]: https://docs.rs/cranelift-simplejit/
+/// [cranelift-faerie]: https://docs.rs/cranelift-faerie/
 pub trait Backend
 where
     Self: marker::Sized,

lib/simplejit/src/backend.rs

@@ -84,6 +84,8 @@ impl SimpleJITBuilder {
 
 /// A `SimpleJITBackend` implements `Backend` and emits code and data into memory where it can be
 /// directly called and accessed.
+///
+/// See the `SimpleJITBuilder` for a convenient way to construct `SimpleJITBackend` instances.
 pub struct SimpleJITBackend {
     isa: Box<TargetIsa>,
     symbols: HashMap<String, *const u8>,