refactor

Author: Byron

gix-actor/src/lib.rs

@@ -71,21 +71,25 @@ pub struct Signature {
 
 /// An immutable signature that is created by an actor at a certain time.
 ///
-/// Not fully parsed.
+/// 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, potentially malformed.
+    /// 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

@@ -72,7 +72,7 @@ mod convert {
     impl Signature {
         /// Borrow this instance as immutable, serializing the `time` field into `buf`.
         ///
-        /// Commonly used as `signature.to_ref(&mut TimeBuf::default())`.
+        /// 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(),
@@ -82,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 {