From c4d9e73126131d31e707822b0fd8b0710363c863 Mon Sep 17 00:00:00 2001 From: Nadrieril Date: Sun, 5 Apr 2020 17:12:08 +0100 Subject: Final doc tweaks --- serde_dhall/src/lib.rs | 4 +-- serde_dhall/src/options.rs | 64 +++++++++++++++++++++--------------------- serde_dhall/src/static_type.rs | 4 ++- serde_dhall/src/value.rs | 45 +++++++++++++++-------------- 4 files changed, 59 insertions(+), 58 deletions(-) (limited to 'serde_dhall/src') 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 HasAnnot 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` 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`] 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`]: 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, - /// } + /// 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::()?; + /// let type_str = "{ x: Natural, y: Natural }"; + /// let ty = from_str(type_str).parse::()?; /// - /// // 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::()?; - /// 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::>()?; + /// 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::() + /// from_str(invalid_data) + /// .type_annotation(&ty) + /// .parse::>() /// .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::()?; - /// 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::()?; /// /// 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>), } -/// 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` -- cgit v1.2.3