Document more

3 files changed, 58 insertions, 26 deletions

diff --git a/serde_dhall/src/shortcuts.rs b/serde_dhall/src/shortcuts.rs
index d88b9ac..54888c5 100644
--- a/serde_dhall/src/shortcuts.rs
+++ b/serde_dhall/src/shortcuts.rs
@@ -4,11 +4,13 @@ use crate::{options, Deserialize, Result, SimpleType, StaticType};
 ///
 /// This will recursively resolve all imports in the expression, and typecheck it before
 /// deserialization. Relative imports will be resolved relative to the current directory.
-/// See [`options`][`options`] for more control over this process.
+/// See [`options`] for more control over this process.
 ///
-/// For additional type safety, prefer [`from_str_static_type`][`from_str_static_type`] or
-/// [`from_str_manual_type`][`from_str_manual_type`].
+/// For additional type safety, prefer [`from_str_static_type`] or [`from_str_manual_type`].
 ///
+/// [`options`]: options/index.html
+/// [`from_str_manual_type`]: fn.from_str_manual_type.html
+/// [`from_str_static_type`]: fn.from_str_static_type.html
 ///
 /// # Example
 ///
@@ -16,6 +18,7 @@ use crate::{options, Deserialize, Result, SimpleType, StaticType};
 /// # fn main() -> serde_dhall::Result<()> {
 /// use serde::Deserialize;
 ///
+/// // We use serde's derive feature
 /// #[derive(Debug, Deserialize)]
 /// struct Point {
 ///     x: u64,
@@ -25,18 +28,15 @@ use crate::{options, Deserialize, Result, SimpleType, StaticType};
 /// // Some Dhall data
 /// let data = "{ x = 1, y = 1 + 1 } : { x: Natural, y: Natural }";
 ///
-/// // Convert the Dhall string to a Point.
+/// // Parse the Dhall string as a Point.
 /// let point: Point = serde_dhall::from_str(data)?;
+///
 /// assert_eq!(point.x, 1);
 /// assert_eq!(point.y, 2);
 ///
 /// # Ok(())
 /// # }
 /// ```
-///
-/// [`options`]: options/index.html
-/// [`from_str_manual_type`]: fn.from_str_manual_type.html
-/// [`from_str_static_type`]: fn.from_str_static_type.html
 pub fn from_str<T>(s: &str) -> Result<T>
 where
     T: Deserialize,
@@ -47,8 +47,16 @@ where
 /// Deserialize an instance of type `T` from a string of Dhall text,
 /// additionally checking that it matches the supplied type.
 ///
-/// Like [`from_str`], but this additionally checks that
-/// the type of the provided expression matches the supplied type.
+/// This will recursively resolve all imports in the expression, and typecheck it against the
+/// supplied type before deserialization. Relative imports will be resolved relative to the current
+/// directory. See [`options`] for more control over this process.
+///
+/// See also [`from_str_static_type`].
+///
+/// [`options`]: options/index.html
+/// [`from_str_static_type`]: fn.from_str_static_type.html
+///
+/// # Example
 ///
 /// ```rust
 /// # fn main() -> serde_dhall::Result<()> {
@@ -75,8 +83,6 @@ where
 /// # Ok(())
 /// # }
 /// ```
-///
-/// TODO
 pub fn from_str_manual_type<T>(s: &str, ty: &SimpleType) -> Result<T>
 where
     T: Deserialize,
@@ -87,9 +93,14 @@ where
 /// Deserialize an instance of type `T` from a string of Dhall text,
 /// additionally checking that it matches the type of `T`.
 ///
-/// Like [from_str], but this additionally checks that
-/// the type of the provided expression matches the output type `T`. The [StaticType] trait
-/// captures Rust types that are valid Dhall types.
+/// `T` must implement the [`StaticType`] trait.
+///
+/// This will recursively resolve all imports in the expression, and typecheck it against the
+/// type of `T`. Relative imports will be resolved relative to the current
+/// directory. See [`options`] for more control over this process.
+///
+/// [`options`]: options/index.html
+/// [`StaticType`]: trait.StaticType.html
 ///
 /// TODO
 pub fn from_str_static_type<T>(s: &str) -> Result<T>
diff --git a/serde_dhall/src/static_type.rs b/serde_dhall/src/static_type.rs
index ffbc3ad..19f1202 100644
--- a/serde_dhall/src/static_type.rs
+++ b/serde_dhall/src/static_type.rs
@@ -2,16 +2,33 @@ use crate::SimpleType;
 
 /// A Rust type that can be represented as a Dhall type.
 ///
-/// A typical example is `Option<bool>`,
-/// represented by the dhall expression `Optional Bool`.
+/// A typical example is `Option<bool>`, represented by the Dhall expression `Optional Bool`.
 ///
-/// This trait can and should be automatically derived.
+/// This trait can be automatically derived, and this is the recommended way of implementing it.
 ///
-/// The representation needs to be independent of the value.
-/// For this reason, something like `HashMap<String, bool>` cannot implement
-/// [StaticType] because each different value would
-/// have a different Dhall record type.
-/// TODO
+/// Some Rust types cannot implement this trait, because there isn't a single Dhall type that
+/// corresponds to them. For example, `HashMap<String, u64>` could correspond to multiple different
+/// Dhall types, e.g. `{ foo: Natural, bar: Natural }` and `{ baz: Natural }`.
+///
+/// # Example
+///
+/// ```rust
+/// # fn main() -> serde_dhall::Result<()> {
+/// use serde_dhall::{SimpleType, StaticType};
+///
+/// #[derive(StaticType)]
+/// struct Foo {
+///     x: bool,
+///     y: Vec<u64>,
+/// }
+///
+/// let ty: SimpleType =
+///     serde_dhall::from_str("{ x: Bool, y: List Natural }")?;
+///
+/// assert_eq!(Foo::static_type(), ty);
+/// # Ok(())
+/// # }
+/// ```
 pub trait StaticType {
     fn static_type() -> SimpleType;
 }
diff --git a/serde_dhall/src/value.rs b/serde_dhall/src/value.rs
index f542f0a..bdc914f 100644
--- a/serde_dhall/src/value.rs
+++ b/serde_dhall/src/value.rs
@@ -36,11 +36,15 @@ pub(crate) enum SimpleValue {
 /// mismatch happened.
 ///
 /// You would typically not manipulate `SimpleType`s by hand but rather let Rust infer it for your
-/// datatype using the [`StaticType`][TODO] trait, and methods that require it like
-/// [`from_file_static_type`][TODO] and [`Options::static_type_annotation`][TODO]. If you need to supply a
+/// datatype using the [`StaticType`] trait, and methods that require it like
+/// [`from_file_static_type`] and [`Options::static_type_annotation`]. If you need to supply a
 /// `SimpleType` manually however, you can deserialize it like any other Dhall value using the
 /// functions provided by this crate.
 ///
+/// [`StaticType`]: trait.StaticType.html
+/// [`from_file_static_type`]: fn.from_file_static_type.html
+/// [`Options::static_type_annotation`]: options/struct.Options.html#method.static_type_annotation
+///
 /// # Examples
 ///
 /// ```rust
@@ -72,7 +76,7 @@ pub(crate) enum SimpleValue {
 /// let ty: SimpleType =
 ///     serde_dhall::from_str("{ x: Bool, y: List Natural }")?;
 ///
-/// assert_eq!(ty, Foo::static_type());
+/// assert_eq!(Foo::static_type(), ty);
 /// # Ok(())
 /// # }
 /// ```