From 2eb651f9196345e4606c3569b3e22baa40188615 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rn-Michael=20Miehe?=
 <40151420+ldericher@users.noreply.github.com>
Date: Sat, 28 Jun 2025 09:24:46 +0000
Subject: [PATCH] [wip] doc for `sharry` module

---
 src/cli.rs          |  2 +-
 src/file/checked.rs |  7 ++++---
 src/sharry/ids.rs   | 47 ++++++++++++++++++++++++---------------------
 3 files changed, 30 insertions(+), 26 deletions(-)

diff --git a/src/cli.rs b/src/cli.rs
index b6dc9ca..730fcb8 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -159,7 +159,7 @@ impl Cli {
         let mut hasher = Blake2b::new().hash_length(16).to_state();
 
         hasher.update(self.get_uri().as_ref());
-        hasher.update(self.alias.as_ref());
+        hasher.update(self.alias.as_ref().as_bytes());
 
         for chk in sorted(&self.files) {
             hasher.update(chk.as_ref());
diff --git a/src/file/checked.rs b/src/file/checked.rs
index fa54124..7aa4d74 100644
--- a/src/file/checked.rs
+++ b/src/file/checked.rs
@@ -11,9 +11,10 @@ use super::{FileTrait, Uploading};
 
 /// Description of an existing, regular file
 ///
-/// - impl Clone for `clap` compatibility
-/// - impl serde for appstate caching
-/// - impl PartialEq..Ord to handle multiple files given
+/// - impl `Clone` for `clap` compatibility
+/// - impl `serde` for cachefile handling
+/// - impl `PartialEq..Ord` to handle multiple files given
+/// - impl `AsRef<[u8]>` for hashing with `blake2b_simd`
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
 pub struct Checked {
     /// canonical path to a regular file
diff --git a/src/sharry/ids.rs b/src/sharry/ids.rs
index b6e21d8..4bd35d3 100644
--- a/src/sharry/ids.rs
+++ b/src/sharry/ids.rs
@@ -4,18 +4,17 @@ use log::{debug, trace};
 use regex::Regex;
 use serde::{Deserialize, Serialize};
 
-#[derive(Serialize, Deserialize, Debug, Clone)]
+/// ID of a public Sharry alias
+///
+/// - impl `From<String>` and `Clone` as this is just a String
+/// - impl `serde` for cachefile handling
+/// - impl `AsRef<str>` for using in a `ureq` header and hashing support
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AliasID(String);
 
-impl fmt::Display for AliasID {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str(&self.0)
-    }
-}
-
-impl AsRef<[u8]> for AliasID {
-    fn as_ref(&self) -> &[u8] {
-        self.0.as_bytes()
+impl AsRef<str> for AliasID {
+    fn as_ref(&self) -> &str {
+        self.0.as_ref()
     }
 }
 
@@ -25,7 +24,12 @@ impl From<String> for AliasID {
     }
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone)]
+/// ID of a Sharry share
+///
+/// - impl `From<String>` and `Clone` as this is just a String
+/// - impl `serde` for cachefile handling
+/// - impl `Display` for formatting compatibility
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ShareID(String);
 
 impl fmt::Display for ShareID {
@@ -40,7 +44,13 @@ impl From<String> for ShareID {
     }
 }
 
-#[derive(Serialize, Deserialize, Debug, Clone)]
+/// ID of a file in a Sharry share
+///
+/// - impl `Clone` as this is just a String
+/// - impl `serde` for cachefile handling
+/// - impl `Display` for formatting compatibility
+/// - impl `TryFrom<String>` for extracting from matching a "PATCH" uri
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct FileID(String);
 
 impl fmt::Display for FileID {
@@ -108,18 +118,11 @@ mod tests {
                 // check AliasID
                 let _ = AliasID(input.to_owned());
                 let aid = AliasID::from(input.to_owned()); // "From" trait
-                assert_eq!(
-                    aid.to_string(),
-                    input,
-                    "`impl Display for AliasID` expected: {:?}, got {:?}",
-                    input,
-                    aid.to_string(),
-                );
                 assert_eq!(
                     aid.as_ref(),
-                    input.as_bytes(),
-                    "`impl AsRef<[u8]> for AliasID` expected: {:?}, got {:?}",
-                    input.as_bytes(),
+                    input,
+                    "`impl AsRef<str> for AliasID` expected: {:?}, got {:?}",
+                    input,
                     aid.as_ref(),
                 );
             }