gix-actor docs: document conversions between Signature and SignatureRef

Cc: github.com/GitoxideLabs/pull/1935

Author: ilyagr

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,
 }

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())`.
         pub fn to_ref<'a>(&'a self, time_buf: &'a mut TimeBuf) -> SignatureRef<'a> {
             SignatureRef {
                 name: self.name.as_ref(),