gix-actor docs: document conversions between Signature and SignatureRef

gix-actor/src/lib.rs

@@ -71,19 +71,25 @@ pub struct Signature {
 
 /// An immutable signature that is created by an actor at a certain time.
 ///
+/// All of its fields are references to the backing buffer to allow lossless
+/// round-tripping, as decoding the `time` field could be a lossy transformation.
+///
 /// Note that this is not a cryptographical signature.
 #[derive(Default, PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct SignatureRef<'a> {
     /// The actors name, potentially with whitespace as parsed.
     ///
-    /// Use [SignatureRef::trim()] or trim manually to be able to clean it up.
+    /// Use [SignatureRef::trim()] or trim manually for cleanup.
     #[cfg_attr(feature = "serde", serde(borrow))]
     pub name: &'a BStr,
     /// The actor's email, potentially with whitespace and garbage as parsed.
     ///
-    /// Use [SignatureRef::trim()] or trim manually to be able to clean it up.
+    /// Use [SignatureRef::trim()] or trim manually for cleanup.
     pub email: &'a BStr,
-    /// The timestamp at which the signature was performed.
+    /// The timestamp at which the signature was performed,
+    /// potentially malformed due to lenient parsing.
+    ///
+    /// Use [`SignatureRef::time()`] to decode.
     pub time: &'a str,
 }

gix-actor/src/signature/mod.rs

@@ -14,7 +14,7 @@ mod _ref {
             decode.parse_next(&mut data)
         }
 
-        /// Create an owned instance from this shared one.
+        /// Try to parse the timestamp and create an owned instance from this shared one.
         pub fn to_owned(&self) -> Result<Signature, gix_date::parse::Error> {
             Ok(Signature {
                 name: self.name.to_owned(),
@@ -71,6 +71,8 @@ mod convert {
 
     impl Signature {
         /// Borrow this instance as immutable, serializing the `time` field into `buf`.
+        ///
+        /// Commonly used as [`signature.to_ref(&mut TimeBuf::default())`](TimeBuf::default).
         pub fn to_ref<'a>(&'a self, time_buf: &'a mut TimeBuf) -> SignatureRef<'a> {
             SignatureRef {
                 name: self.name.as_ref(),
@@ -80,6 +82,7 @@ mod convert {
         }
     }
 
+    /// Note that this conversion is lossy due to the lenient parsing of the [`time`](SignatureRef::time) field.
     impl From<SignatureRef<'_>> for Signature {
         fn from(other: SignatureRef<'_>) -> Signature {
             Signature {