summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNadrieril2020-04-05 17:12:08 +0100
committerNadrieril2020-04-05 17:12:08 +0100
commitc4d9e73126131d31e707822b0fd8b0710363c863 (patch)
treef3fbc16ba580c865398d90a5d3e2cf9b17e0bbfc
parent75c0f328c7b6d404353fd078ae12417766ef8a32 (diff)
Final doc tweaks
Diffstat (limited to '')
-rw-r--r--serde_dhall/src/lib.rs4
-rw-r--r--serde_dhall/src/options.rs64
-rw-r--r--serde_dhall/src/static_type.rs4
-rw-r--r--serde_dhall/src/value.rs45
4 files changed, 59 insertions, 58 deletions
diff --git a/serde_dhall/src/lib.rs b/serde_dhall/src/lib.rs
index 08ca4a5..c478b2a 100644
--- a/serde_dhall/src/lib.rs
+++ b/serde_dhall/src/lib.rs
@@ -154,9 +154,9 @@
//! # Controlling deserialization
//!
//! If you need more control over the process of reading Dhall values, e.g. disabling
-//! imports, see the [`options`] module.
+//! imports, see the [`Deserializer`] methods.
//!
-//! [`options`]: options/index.html
+//! [`Deserializer`]: struct.Deserializer.html
//! [dhall]: https://dhall-lang.org/
//! [serde]: https://docs.serde.rs/serde/
//! [serde::Deserialize]: https://docs.serde.rs/serde/trait.Deserialize.html
diff --git a/serde_dhall/src/options.rs b/serde_dhall/src/options.rs
index ca1e58c..06a4368 100644
--- a/serde_dhall/src/options.rs
+++ b/serde_dhall/src/options.rs
@@ -43,9 +43,15 @@ impl<T: StaticType> HasAnnot<StaticAnnot> for T {
/// This builder exposes the ability to configure how a value is deserialized and what operations
/// are permitted during evaluation.
///
-/// Generally speaking, when using `Deserializer`, you'll create it with `from_str` or `from_file`, then
-/// chain calls to methods to set each option, then call `parse`. This will give you a
-/// `serde_dhall::Result<T>` where `T` is a deserializable type of your choice.
+/// Generally speaking, when using [`Deserializer`], you'll create it with [`from_str`] or [`from_file`], then
+/// chain calls to methods to set each option, then call [`parse`]. This will give you a
+/// [`Result<T>`] where `T` is a deserializable type of your choice.
+///
+/// [`Deserializer`]: struct.Deserializer.html
+/// [`from_str`]: fn.from_str.html
+/// [`from_file`]: fn.from_file.html
+/// [`parse`]: struct.Deserializer.html#method.parse
+/// [`Result<T>`]: type.Result.html
///
/// # Examples
///
@@ -106,39 +112,33 @@ impl<'a> Deserializer<'a, NoAnnot> {
/// Ensures that the parsed value matches the provided type.
///
/// In many cases the Dhall type that corresponds to a Rust type can be inferred automatically.
- /// See the [`StaticType`] trait and the [`static_type_annotation`] method.
+ /// See the [`StaticType`] trait and the [`static_type_annotation`] method for that.
///
/// # Example
///
/// ```
/// # fn main() -> serde_dhall::Result<()> {
+ /// use std::collections::HashMap;
/// use serde::Deserialize;
- /// use serde_dhall::SimpleType;
- ///
- /// #[derive(Deserialize)]
- /// struct Point {
- /// x: u64,
- /// y: Option<u64>,
- /// }
+ /// use serde_dhall::{from_str, SimpleType};
///
/// // Parse a Dhall type
- /// let point_type_str = "{ x: Natural, y: Optional Natural }";
- /// let point_type = serde_dhall::from_str(point_type_str).parse::<SimpleType>()?;
+ /// let type_str = "{ x: Natural, y: Natural }";
+ /// let ty = from_str(type_str).parse::<SimpleType>()?;
///
- /// // Parse some Dhall data to a Point.
- /// let data = "{ x = 1, y = Some (1 + 1) }";
- /// let point = serde_dhall::from_str(data)
- /// .type_annotation(&point_type)
- /// .parse::<Point>()?;
- /// assert_eq!(point.x, 1);
- /// assert_eq!(point.y, Some(2));
+ /// // Parse some Dhall data.
+ /// let data = "{ x = 1, y = 1 + 1 }";
+ /// let point = from_str(data)
+ /// .type_annotation(&ty)
+ /// .parse::<HashMap<String, usize>>()?;
+ /// assert_eq!(point.get("y"), Some(&2));
///
/// // Invalid data fails the type validation; deserialization would have succeeded otherwise.
- /// let invalid_data = "{ x = 1 }";
+ /// let invalid_data = "{ x = 1, z = 3 }";
/// assert!(
- /// serde_dhall::from_str(invalid_data)
- /// .type_annotation(&point_type)
- /// .parse::<Point>()
+ /// from_str(invalid_data)
+ /// .type_annotation(&ty)
+ /// .parse::<HashMap<String, usize>>()
/// .is_err()
/// );
/// # Ok(())
@@ -272,7 +272,7 @@ impl<'a, A> Deserializer<'a, A> {
/// Parses the chosen dhall value with the options provided.
///
- /// If you enabled static annotations, `T` is additional required to implement [`StaticType`].
+ /// If you enabled static annotations, `T` is required to implement [`StaticType`].
///
///
/// # Example
@@ -280,7 +280,7 @@ impl<'a, A> Deserializer<'a, A> {
/// ```
/// # fn main() -> serde_dhall::Result<()> {
/// let data = serde_dhall::from_str("6 * 7").parse::<u64>()?;
- /// assert_eq!(data, 42)
+ /// assert_eq!(data, 42);
/// # Ok(())
/// # }
/// ```
@@ -297,10 +297,10 @@ impl<'a, A> Deserializer<'a, A> {
}
}
-/// Deserialize an instance of type `T` from a string of Dhall text.
+/// Deserialize a value from a string of Dhall text.
///
-/// This returns a [`Deserializer`] object. Call the [`parse`] method to get the deserialized value, or
-/// use other [`Deserializer`] methods to e.g. add type annotations beforehand.
+/// This returns a [`Deserializer`] object. Call the [`parse`] method to get the deserialized
+/// value, or use other [`Deserializer`] methods to control the deserialization process.
///
/// # Example
///
@@ -333,10 +333,10 @@ pub fn from_str(s: &str) -> Deserializer<'_, NoAnnot> {
Deserializer::from_str(s)
}
-/// Deserialize an instance of type `T` from a Dhall file.
+/// Deserialize a value from a Dhall file.
///
-/// This returns a [`Deserializer`] object. Call the [`parse`] method to get the deserialized value, or
-/// use other [`Deserializer`] methods to e.g. add type annotations beforehand.
+/// This returns a [`Deserializer`] object. Call the [`parse`] method to get the deserialized
+/// value, or use other [`Deserializer`] methods to control the deserialization process.
///
/// # Example
///
diff --git a/serde_dhall/src/static_type.rs b/serde_dhall/src/static_type.rs
index 6e76424..f7b72b5 100644
--- a/serde_dhall/src/static_type.rs
+++ b/serde_dhall/src/static_type.rs
@@ -71,7 +71,9 @@ pub trait StaticType {
/// }
/// }
///
- /// let foo: Foo = serde_dhall::from_str("[ 1, 2 ]").static_type_annotation().parse()?;
+ /// let foo = serde_dhall::from_str("[ 1, 2 ]")
+ /// .static_type_annotation()
+ /// .parse::<Foo>()?;
///
/// assert_eq!(foo.0, vec![1, 2]);
/// # Ok(())
diff --git a/serde_dhall/src/value.rs b/serde_dhall/src/value.rs
index f21e836..7baeee9 100644
--- a/serde_dhall/src/value.rs
+++ b/serde_dhall/src/value.rs
@@ -28,7 +28,7 @@ pub(crate) enum SimpleValue {
Union(String, Option<Box<SimpleValue>>),
}
-/// The type of a value that can be decoded by Serde, e.g. `{ x: Bool, y: List Natural }`.
+/// The type of a value that can be decoded by `serde_dhall`, e.g. `{ x: Bool, y: List Natural }`.
///
/// A `SimpleType` is used when deserializing values to ensure they are of the expected type.
/// Rather than letting `serde` handle potential type mismatches, this uses the type-checking
@@ -36,35 +36,17 @@ 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`] 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.
+/// datatype by deriving the [`StaticType`] trait, and using
+/// [`Deserializer::static_type_annotation`]. If you need to supply a `SimpleType` manually, you
+/// can either deserialize it like any other Dhall value, or construct it manually.
///
/// [`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
+/// [`Deserializer::static_type_annotation`]: options/struct.Deserializer.html#method.static_type_annotation
///
/// # Examples
///
/// ```rust
/// # fn main() -> serde_dhall::Result<()> {
-/// use std::collections::HashMap;
-/// use serde_dhall::SimpleType;
-///
-/// let ty: SimpleType =
-/// serde_dhall::from_str("{ x: Natural, y: Natural }").parse()?;
-///
-/// let mut map = HashMap::new();
-/// map.insert("x".to_string(), SimpleType::Natural);
-/// map.insert("y".to_string(), SimpleType::Natural);
-/// assert_eq!(ty, SimpleType::Record(map));
-/// # Ok(())
-/// # }
-/// ```
-///
-/// ```rust
-/// # fn main() -> serde_dhall::Result<()> {
/// use serde_dhall::{SimpleType, StaticType};
///
/// #[derive(StaticType)]
@@ -80,6 +62,23 @@ pub(crate) enum SimpleValue {
/// # Ok(())
/// # }
/// ```
+///
+/// ```rust
+/// # fn main() -> serde_dhall::Result<()> {
+/// use std::collections::HashMap;
+/// use serde_dhall::SimpleType;
+///
+/// let ty: SimpleType =
+/// serde_dhall::from_str("{ x: Natural, y: Natural }").parse()?;
+///
+/// let mut map = HashMap::new();
+/// map.insert("x".to_string(), SimpleType::Natural);
+/// map.insert("y".to_string(), SimpleType::Natural);
+/// assert_eq!(ty, SimpleType::Record(map));
+/// # Ok(())
+/// # }
+/// ```
+///
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SimpleType {
/// Corresponds to the Dhall type `Bool`