Document all of the API

Closes #64

4 files changed, 60 insertions, 10 deletions

diff --git a/dhall/src/expr.rs b/dhall/src/expr.rs
index 6f9f280..a84b41d 100644
--- a/dhall/src/expr.rs
+++ b/dhall/src/expr.rs
@@ -50,7 +50,12 @@ pub(crate) struct Normalized<'a>(
 );
 derive_other_traits!(Normalized);
 
-/// An expression of type `Type` (like `Bool` or `Natural -> Text`, but not `Type`)
+/// A Dhall expression representing a simple type.
+///
+/// This captures what is usually simply called a "type", like
+/// `Bool`, `{ x: Integer }` or `Natural -> Text`.
+///
+/// For a more general notion of "type", see [Type].
 #[derive(Debug, Clone, Eq)]
 pub struct SimpleType<'a>(
     pub(crate) SubExpr<X, X>,
@@ -58,13 +63,17 @@ pub struct SimpleType<'a>(
 );
 derive_other_traits!(SimpleType);
 
+/// A Dhall expression representing a (possibly higher-kinded) type.
+///
+/// This includes [SimpleType]s but also higher-kinded expressions like
+/// `Type`, `Kind` and `{ x: Type }`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Type<'a>(pub(crate) TypeInternal<'a>);
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) enum TypeInternal<'a> {
     Expr(Box<Normalized<'a>>),
-    // The type of `Sort`
+    /// The type of `Sort`
     SuperType,
 }
 
diff --git a/dhall/src/lib.rs b/dhall/src/lib.rs
index 73f3c1b..51fb6b7 100644
--- a/dhall/src/lib.rs
+++ b/dhall/src/lib.rs
@@ -13,7 +13,7 @@
 //! [Dhall][dhall] is a programmable configuration language that provides a non-repetitive
 //! alternative to JSON and YAML.
 //!
-//! You can think of Dhall as: JSON/YAML + types + imports + functions
+//! You can think of Dhall as: JSON + types + imports + functions
 //!
 //! For a description of the dhall language, examples, tutorials, and more, see the [language
 //! website][dhall].
@@ -130,10 +130,19 @@ mod typecheck;
 pub use crate::traits::{Deserialize, SimpleStaticType, StaticType};
 #[doc(hidden)]
 pub use dhall_generator::SimpleStaticType;
+/// When manipulating Dhall expressions goes wrong.
 pub mod error;
 pub mod expr;
 mod serde;
 
+/// Deserialize an instance of type T from a string of Dhall text.
+///
+/// This will recursively resolve all imports in the expression, and
+/// typecheck it. More control over this process is not yet available
+/// but will be in a coming verions of this crate.
+///
+/// If a type is provided, this additionally checks that the provided
+/// expression has that type.
 pub fn from_str<'a, T: Deserialize<'a>>(
     s: &'a str,
     ty: Option<&crate::expr::Type>,
@@ -141,6 +150,12 @@ pub fn from_str<'a, T: Deserialize<'a>>(
     T::from_str(s, ty)
 }
 
+/// Deserialize an instance of type T from a string of Dhall text,
+/// additionally checking that it matches the type of T.
+///
+/// This will recursively resolve all imports in the expression, and
+/// typecheck it. More control over this process is not yet available
+/// but will be in a coming verions of this crate.
 pub fn from_str_auto_type<'a, T: Deserialize<'a> + StaticType>(
     s: &'a str,
 ) -> crate::error::Result<T> {
diff --git a/dhall/src/traits/deserialize.rs b/dhall/src/traits/deserialize.rs
index f1be054..e2e0b05 100644
--- a/dhall/src/traits/deserialize.rs
+++ b/dhall/src/traits/deserialize.rs
@@ -1,7 +1,14 @@
 use crate::error::*;
 use crate::expr::*;
 
+/// A data structure that can be deserialized from a Dhall expression
+///
+/// This is automatically implemented for any type that [serde][serde]
+/// can deserialize.
+///
+/// This trait cannot be implemented manually.
 pub trait Deserialize<'a>: Sized {
+    /// See [dhall::from_str][crate::from_str]
     fn from_str(s: &'a str, ty: Option<&Type>) -> Result<Self>;
 }
 
diff --git a/dhall/src/traits/static_type.rs b/dhall/src/traits/static_type.rs
index 35d91e1..444f464 100644
--- a/dhall/src/traits/static_type.rs
+++ b/dhall/src/traits/static_type.rs
@@ -2,15 +2,32 @@ use crate::expr::*;
 use dhall_core::*;
 use dhall_generator::*;
 
+/// A value that has a statically-known Dhall type.
+///
+/// This trait is strictly more general than [SimpleStaticType].
+/// The reason is that it allows an arbitrary [Type] to be returned
+/// instead of just a [SimpleType].
+///
+/// For now the only interesting impl is [SimpleType] itself, who
+/// has a statically-known type which is not itself a [SimpleType].
 pub trait StaticType {
     fn get_static_type() -> Type<'static>;
 }
 
-/// Trait for rust types that can be represented in dhall in
-/// a single way, independent of the value. A typical example is `Option<bool>`,
-/// represented by the dhall expression `Optional Bool`. A typical counterexample
-/// is `HashMap<Text, bool>` because dhall cannot represent records with a
-/// variable number of fields.
+/// A Rust type that can be represented as a Dhall type.
+///
+/// A typical example is `Option<bool>`,
+/// represented by the dhall expression `Optional Bool`.
+///
+/// This trait can and should be automatically derived.
+///
+/// The representation needs to be independent of the value.
+/// For this reason, something like `HashMap<String, bool>` cannot implement
+/// [SimpleStaticType] because each different value would
+/// have a different Dhall record type.
+///
+/// The `Simple` in `SimpleStaticType` indicates that the returned type is
+/// a [SimpleType].
 pub trait SimpleStaticType {
     fn get_simple_static_type<'a>() -> SimpleType<'a>;
 }
@@ -31,6 +48,8 @@ impl<T: SimpleStaticType> StaticType for T {
 }
 
 impl<'a> StaticType for SimpleType<'a> {
+    /// By definition, a [SimpleType] has type `Type`.
+    /// This returns the Dhall expression `Type`
     fn get_static_type() -> Type<'static> {
         Type::const_type()
     }
@@ -106,8 +125,8 @@ impl<T: SimpleStaticType> SimpleStaticType for Vec<T> {
     }
 }
 
-impl<'b, T: SimpleStaticType> SimpleStaticType for &'b T {
-    fn get_simple_static_type<'a>() -> SimpleType<'a> {
+impl<'a, T: SimpleStaticType> SimpleStaticType for &'a T {
+    fn get_simple_static_type<'b>() -> SimpleType<'b> {
         T::get_simple_static_type()
     }
 }