From 05fbaff2dc2ad4292353acf84b691861f1bbf85c Mon Sep 17 00:00:00 2001 From: Paul Spooren Date: Fri, 8 Nov 2024 12:44:30 +0100 Subject: [PATCH] docs(to): fix docstrings and add examples Signed-off-by: Paul Spooren --- to/src/lib.rs | 2 ++ to/src/to/beside.rs | 47 +++++++++++++++++++++++++++++++++++ to/src/to/condense.rs | 2 ++ to/src/to/dst_coercion.rs | 1 + to/src/to/to_trait.rs | 15 ++++++----- to/src/to/with_destination.rs | 26 +++++++++++++++++++ 6 files changed, 87 insertions(+), 6 deletions(-) diff --git a/to/src/lib.rs b/to/src/lib.rs index 5cd4ec58..0f52446c 100644 --- a/to/src/lib.rs +++ b/to/src/lib.rs @@ -1,3 +1,5 @@ +#![warn(missing_docs)] +#![recursion_limit = "256"] #![doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/README.md"))] #[cfg(doctest)] diff --git a/to/src/to/beside.rs b/to/src/to/beside.rs index 1a6d5ed6..8473dfe3 100644 --- a/to/src/to/beside.rs +++ b/to/src/to/beside.rs @@ -5,23 +5,70 @@ use crate::CondenseBeside; pub struct Beside(pub Val, pub Ret); impl Beside { + /// Get an immutable reference to the destination value + /// + /// # Example + /// ``` + /// use rosenpass_to::Beside; + /// + /// let beside = Beside(1, 2); + /// assert_eq!(beside.dest(), &1); + /// ``` pub fn dest(&self) -> &Val { &self.0 } + /// Get an immutable reference to the return value + /// + /// # Example + /// ``` + /// use rosenpass_to::Beside; + /// + /// let beside = Beside(1, 2); + /// assert_eq!(beside.ret(), &2); + /// ``` pub fn ret(&self) -> &Ret { &self.1 } + /// Get a mutable reference to the destination value + /// + /// # Example + /// ``` + /// use rosenpass_to::Beside; + /// + /// let mut beside = Beside(1, 2); + /// *beside.dest_mut() = 3; + /// assert_eq!(beside.dest(), &3); + /// ``` pub fn dest_mut(&mut self) -> &mut Val { &mut self.0 } + /// Get a mutable reference to the return value + /// + /// # Example + /// ``` + /// use rosenpass_to::Beside; + /// + /// let mut beside = Beside(1, 2); + /// *beside.ret_mut() = 3; + /// assert_eq!(beside.ret(), &3); + /// ``` pub fn ret_mut(&mut self) -> &mut Ret { &mut self.1 } /// Perform beside condensation. See [CondenseBeside] + /// + /// # Example + /// ``` + /// use rosenpass_to::Beside; + /// use rosenpass_to::CondenseBeside; + /// + /// let beside = Beside(1, ()); + /// assert_eq!(beside.condense(), 1); + /// ``` pub fn condense(self) -> >::Condensed where Ret: CondenseBeside, diff --git a/to/src/to/condense.rs b/to/src/to/condense.rs index 3ac7b90d..b9df4ba5 100644 --- a/to/src/to/condense.rs +++ b/to/src/to/condense.rs @@ -7,8 +7,10 @@ /// The function [Beside::condense()](crate::Beside::condense) is a shorthand for using the /// condense trait. pub trait CondenseBeside { + /// The type that results from condensation. type Condensed; + /// Takes ownership of `self` and condenses it with the given value. fn condense(self, ret: Val) -> Self::Condensed; } diff --git a/to/src/to/dst_coercion.rs b/to/src/to/dst_coercion.rs index cb9aa3a3..fec6db59 100644 --- a/to/src/to/dst_coercion.rs +++ b/to/src/to/dst_coercion.rs @@ -1,6 +1,7 @@ /// Helper performing explicit unsized coercion. /// Used by the [to](crate::to()) function. pub trait DstCoercion { + /// Performs an explicit coercion to the destination type. fn coerce_dest(&mut self) -> &mut Dst; } diff --git a/to/src/to/to_trait.rs b/to/src/to/to_trait.rs index e8fc2bfa..63ad1771 100644 --- a/to/src/to/to_trait.rs +++ b/to/src/to/to_trait.rs @@ -1,13 +1,16 @@ use crate::{Beside, CondenseBeside}; use std::borrow::BorrowMut; -// The To trait is the core of the to crate; most functions with destinations will either return -// an object that is an instance of this trait or they will return `-> impl To impl To: Sized { + /// Writes self to the destination `out` and returns a value of type `Ret`. + /// + /// This is the core method that must be implemented by all types implementing `To`. fn to(self, out: &mut Dst) -> Ret; /// Generate a destination on the fly with a lambda. diff --git a/to/src/to/with_destination.rs b/to/src/to/with_destination.rs index a08cb5ec..6fbec1e5 100644 --- a/to/src/to/with_destination.rs +++ b/to/src/to/with_destination.rs @@ -1,20 +1,38 @@ use crate::To; use std::marker::PhantomData; +/// A struct that wraps a closure and implements the `To` trait +/// +/// This allows passing closures that operate on a destination type `Dst` +/// and return `Ret`. +/// +/// # Type Parameters +/// * `Dst` - The destination type the closure operates on +/// * `Ret` - The return type of the closure +/// * `Fun` - The closure type that implements `FnOnce(&mut Dst) -> Ret` struct ToClosure where Dst: ?Sized, Fun: FnOnce(&mut Dst) -> Ret, { + /// The function to call. fun: Fun, + /// Phantom data to hold the destination type _val: PhantomData>, } +/// Implementation of the `To` trait for ToClosure +/// +/// This enables calling the wrapped closure with a destination reference. impl To for ToClosure where Dst: ?Sized, Fun: FnOnce(&mut Dst) -> Ret, { + /// Execute the wrapped closure with the given destination + /// + /// # Arguments + /// * `out` - Mutable reference to the destination fn to(self, out: &mut Dst) -> Ret { (self.fun)(out) } @@ -22,6 +40,14 @@ where /// Used to create a function with destination. /// +/// Creates a wrapper that implements the `To` trait for a closure that +/// operates on a destination type. +/// +/// # Type Parameters +/// * `Dst` - The destination type the closure operates on +/// * `Ret` - The return type of the closure +/// * `Fun` - The closure type that implements `FnOnce(&mut Dst) -> Ret` +/// /// See the tutorial in [readme.me].. pub fn with_destination(fun: Fun) -> impl To where