summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNadrieril2020-03-22 22:59:11 +0000
committerNadrieril2020-03-31 21:45:32 +0100
commit25c879e802e90a447e10e5f9a0f522217e34f20d (patch)
tree8e2bfbb5d01c70567f38ffb9ecdfa0e86a293f70
parent3a5f2044954aae7278f16e30561a81626dba6923 (diff)
Document more
-rw-r--r--serde_dhall/src/shortcuts.rs41
-rw-r--r--serde_dhall/src/static_type.rs33
-rw-r--r--serde_dhall/src/value.rs10
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(())
/// # }
/// ```