der: document RefToOwned and OwnedToRef (#1498)

der/src/lib.rs

@@ -291,6 +291,12 @@
 //! # }
 //! ```
 //!
+//! ## Owned vs Borrowed
+//!
+//! This crate exposes owned and borrowed objects for representing the same structure.
+//!
+//! [`RefToOwned`] and [`OwnedToRef`] are provided to convert objects from one to the other.
+//!
 //! # See also
 //! For more information about ASN.1 DER we recommend the following guides:
 //!
@@ -322,6 +328,8 @@
 //! [`UintRef`]: asn1::UintRef
 //! [`UtcTime`]: asn1::UtcTime
 //! [`Utf8StringRef`]: asn1::Utf8StringRef
+//! [`RefToOwned`]: referenced::RefToOwned
+//! [`OwnedToRef`]: referenced::OwnedToRef
 
 #[cfg(feature = "alloc")]
 #[allow(unused_imports)]

der/src/referenced.rs

@@ -1,6 +1,13 @@
 //! A module for working with referenced data.
 
 /// A trait for borrowing data from an owned struct
+///
+/// This converts an object owning the data to one that will borrowing the content.
+/// The newly created object lifetime will be tied to the object owning the data.
+///
+/// This is similar to [`alloc::borrow::Borrow`] or [`core::convert::AsRef`] but this returns
+/// an owned structure that references directly the backing slices instead of borrowing
+/// the whole structure.
 pub trait OwnedToRef {
     /// The resulting type referencing back to Self
     type Borrowed<'a>
@@ -13,7 +20,10 @@ pub trait OwnedToRef {
 
 /// A trait for cloning a referenced structure and getting owned objects
 ///
-/// This is the pendant to [`OwnedToRef`]
+/// This is the pendant to [`OwnedToRef`].
+///
+/// This converts an object borrowing data to one that will copy the data over and
+/// own the content.
 pub trait RefToOwned<'a> {
     /// The resulting type after obtaining ownership.
     type Owned: OwnedToRef<Borrowed<'a> = Self>

spki/src/spki.rs

@@ -21,9 +21,13 @@ use crate::{fingerprint, FingerprintBytes};
 use der::pem::PemLabel;
 
 /// [`SubjectPublicKeyInfo`] with [`AnyRef`] algorithm parameters, and [`BitStringRef`] params.
+///
+/// This is the borrowing-pendant to [`SubjectPublicKeyInfoOwned`].
 pub type SubjectPublicKeyInfoRef<'a> = SubjectPublicKeyInfo<AnyRef<'a>, BitStringRef<'a>>;
 
 /// [`SubjectPublicKeyInfo`] with [`Any`] algorithm parameters, and [`BitString`] params.
+///
+/// This is the owning-pendant to [`SubjectPublicKeyInfoRef`].
 #[cfg(feature = "alloc")]
 pub type SubjectPublicKeyInfoOwned = SubjectPublicKeyInfo<Any, BitString>;