[wip] documentation

- added more notes
- `main.rs` logging
- clearer matching of `ClientError::ResponseStatus`

notes.md

@@ -1,4 +1,4 @@
-outline of sharry uploading
+# Outline of sharry upload API
 
 1. POST to "new" route
     - uri: https://sharry.yavook.de/api/v2/alias/upload/new
@@ -32,10 +32,29 @@ outline of sharry uploading
     - res.status == 200
     - res_json.success, res_json.message
 
-hints
 
-- https://stackoverflow.com/questions/59586787/rust-how-to-do-http-put-of-large-files
+# Links
 
-ideas
+- yvk repo: https://code.yavook.de/jmm/shrupl
+- sharry issue: https://github.com/eikek/sharry/issues/1659
+- ureq: https://stackoverflow.com/questions/59586787/rust-how-to-do-http-put-of-large-files
+- hashing: https://duckduckgo.com/?q=rust+get+file+hash&t=canonical&ia=web
+    - https://stackoverflow.com/q/69787906
+    - https://github.com/RustCrypto/hashes
 
-- max errors => stop
+
+# Ideas
+
+- cli functions
+    - max retries => stop
+    - "continue" and "new" flags to avoid user interaction
+    - "quiet" flag to disable output entirely
+    - "verbose" flag to adjust RUST_LOG for `shrupl` crate
+
+- client error rework
+    - current variants are too "low level"
+    - use variants like `InvalidEndpoint`, `InvalidAlias` etc.
+
+- hashing
+    - store file hashes with all `file::*` variants
+    - check hashes on "continue"

src/file/checked.rs

@@ -9,13 +9,26 @@ use crate::sharry;
 
 use super::{FileTrait, Uploading};
 
+/// Description of an existing, regular file
+///
+/// - impl Debug, Clone, Hash for `clap` compatibility
+/// - impl serde for appstate caching
+/// - impl Ord to handle multiple files given
 #[derive(Debug, Clone, Hash, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
 pub struct Checked {
+    /// canonical path to a regular file
     path: PathBuf,
+    /// size of that file
     size: u64,
 }
 
 impl Checked {
+    /// create a new checked file from some path reference
+    ///
+    /// # Errors
+    ///
+    /// - calls `fs::metadata(path)` or `fs::canonicalize`
+    /// - path does not correspond to a regular file
     pub fn new(value: impl AsRef<Path>) -> io::Result<Self> {
         let meta = fs::metadata(&value)?;
         if meta.is_file() {
@@ -31,6 +44,15 @@ impl Checked {
         }
     }
 
+    /// start uploading this file
+    ///
+    /// - tries to create a new entry in a share
+    /// - expects endpoint like `{base_uri}/alias/upload/{share_id}/files/tus`
+    /// - consumes `self` into a `file::Uploading` struct
+    ///
+    /// # Errors
+    ///
+    /// -
     pub fn start_upload(
         self,
         client: &impl sharry::Client,
@@ -51,6 +73,7 @@ impl<'t> FileTrait<'t> for Checked {
         <Self as FileTrait>::extract_file_name(&self.path)
     }
 
+    /// get the file's size
     fn get_size(&self) -> u64 {
         self.size
     }

src/file/mod.rs

@@ -20,7 +20,9 @@ pub trait FileTrait<'t> {
             .expect("bad file name")
     }
 
+    /// get a reference to the file's name
     fn get_name(&'t self) -> &'t str;
 
+    /// get the file's size
     fn get_size(&self) -> u64;
 }

src/main.rs

@@ -50,10 +50,7 @@ fn prompt_continue() -> bool {
 fn print_error(e: &ClientError) {
     if let Some(cause) = match e {
         // known errors
-        ClientError::ResponseStatus {
-            actual: 403,
-            expected: _,
-        } => Some("Alias ID"),
+        ClientError::ResponseStatus { actual: 403, .. } => Some("Alias ID"),
         ClientError::StdIo(_) => Some("URL"),
         // unknown error
         _ => None,
@@ -100,7 +97,7 @@ fn main() {
     };
 
     let args = Cli::parse();
-    info!("args: {args:?}");
+    info!("args: {args:#?}");
 
     let mut state = AppState::try_resume(&args)
         .and_then(|state| prompt_continue().then_some(state))
@@ -125,7 +122,7 @@ fn main() {
             }
         });
 
-    info!("continuing with state: {state:?}");
+    info!("continuing with state: {state:#?}");
 
     let fns_magenta = state
         .file_names()