diff --git a/gix-actor/src/lib.rs b/gix-actor/src/lib.rs index e5f7ac87cd0..bc7ccc8a9b7 100644 --- a/gix-actor/src/lib.rs +++ b/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, } diff --git a/gix-actor/src/signature/mod.rs b/gix-actor/src/signature/mod.rs index f7f7b331e43..ecb702dbd10 100644 --- a/gix-actor/src/signature/mod.rs +++ b/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 {