From 8bebd2e84b4e9d9a31a6ff8dcd17da83534f3c95 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Thu, 5 Jun 2025 15:51:03 -0700 Subject: [PATCH 1/2] gix-actor docs: document conversions between `Signature` and `SignatureRef` Cc: https://github.com/GitoxideLabs/gitoxide/pull/1935 --- gix-actor/src/lib.rs | 4 +++- gix-actor/src/signature/mod.rs | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/gix-actor/src/lib.rs b/gix-actor/src/lib.rs index e5f7ac87cd0..ab1361b456e 100644 --- a/gix-actor/src/lib.rs +++ b/gix-actor/src/lib.rs @@ -71,6 +71,8 @@ pub struct Signature { /// An immutable signature that is created by an actor at a certain time. /// +/// Not fully parsed. +/// /// 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))] @@ -84,6 +86,6 @@ pub struct SignatureRef<'a> { /// /// Use [SignatureRef::trim()] or trim manually to be able to clean it up. pub email: &'a BStr, - /// The timestamp at which the signature was performed. + /// The timestamp at which the signature was performed, potentially malformed. pub time: &'a str, } diff --git a/gix-actor/src/signature/mod.rs b/gix-actor/src/signature/mod.rs index f7f7b331e43..b300ff4baf8 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 { 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())`. pub fn to_ref<'a>(&'a self, time_buf: &'a mut TimeBuf) -> SignatureRef<'a> { SignatureRef { name: self.name.as_ref(), From aff23d65a1a44e5356fb362a857d736280d3a580 Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Fri, 6 Jun 2025 04:53:41 +0200 Subject: [PATCH 2/2] refactor --- gix-actor/src/lib.rs | 12 ++++++++---- gix-actor/src/signature/mod.rs | 3 ++- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/gix-actor/src/lib.rs b/gix-actor/src/lib.rs index ab1361b456e..bc7ccc8a9b7 100644 --- a/gix-actor/src/lib.rs +++ b/gix-actor/src/lib.rs @@ -71,7 +71,8 @@ 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)] @@ -79,13 +80,16 @@ pub struct Signature { 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, } diff --git a/gix-actor/src/signature/mod.rs b/gix-actor/src/signature/mod.rs index b300ff4baf8..ecb702dbd10 100644 --- a/gix-actor/src/signature/mod.rs +++ b/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> for Signature { fn from(other: SignatureRef<'_>) -> Signature { Signature {