docs: add documentation comments to crate

Also, make it an error for a public symbol to not be documented.

Sponsored-by: author

13 files changed, 83 insertions, 4 deletions

diff --git a/src/cmd/backup.rs b/src/cmd/backup.rs
index 8f3d6d5..6e09d37 100644
--- a/src/cmd/backup.rs
+++ b/src/cmd/backup.rs
@@ -1,3 +1,5 @@
+//! The `backup` subcommand.
+
 use crate::backup_run::BackupRun;
 use crate::client::AsyncBackupClient;
 use crate::config::ClientConfig;
@@ -10,10 +12,12 @@ use structopt::StructOpt;
 use tempfile::NamedTempFile;
 use tokio::runtime::Runtime;
 
+/// Make a backup.
 #[derive(Debug, StructOpt)]
 pub struct Backup {}
 
 impl Backup {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let rt = Runtime::new()?;
         rt.block_on(self.run_async(config))
diff --git a/src/cmd/chunk.rs b/src/cmd/chunk.rs
index e0e91b1..445d23f 100644
--- a/src/cmd/chunk.rs
+++ b/src/cmd/chunk.rs
@@ -1,3 +1,5 @@
+//! The `encrypt-chunk` and `decrypt-chunk` subcommands.
+
 use crate::chunk::DataChunk;
 use crate::chunkmeta::ChunkMeta;
 use crate::cipher::CipherEngine;
@@ -6,19 +8,24 @@ use crate::error::ObnamError;
 use std::path::PathBuf;
 use structopt::StructOpt;
 
+/// Encrypt a chunk.
 #[derive(Debug, StructOpt)]
 pub struct EncryptChunk {
+    /// The name of the file containing the cleartext chunk.
     #[structopt(parse(from_os_str))]
     filename: PathBuf,
 
+    /// Name of file where to write the encrypted chunk.
     #[structopt(parse(from_os_str))]
     output: PathBuf,
 
+    /// Chunk metadata as JSON.
     #[structopt()]
     json: String,
 }
 
 impl EncryptChunk {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let pass = config.passwords()?;
         let cipher = CipherEngine::new(&pass);
@@ -35,19 +42,24 @@ impl EncryptChunk {
     }
 }
 
+/// Decrypt a chunk.
 #[derive(Debug, StructOpt)]
 pub struct DecryptChunk {
+    /// Name of file containing encrypted chunk.
     #[structopt(parse(from_os_str))]
     filename: PathBuf,
 
+    /// Name of file where to write the cleartext chunk.
     #[structopt(parse(from_os_str))]
     output: PathBuf,
 
+    /// Chunk metadata as JSON.
     #[structopt()]
     json: String,
 }
 
 impl DecryptChunk {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let pass = config.passwords()?;
         let cipher = CipherEngine::new(&pass);
diff --git a/src/cmd/chunkify.rs b/src/cmd/chunkify.rs
index 79fbdea..e2ce05f 100644
--- a/src/cmd/chunkify.rs
+++ b/src/cmd/chunkify.rs
@@ -1,3 +1,5 @@
+//! The `chunkify` subcommand.
+
 use crate::config::ClientConfig;
 use crate::engine::Engine;
 use crate::error::ObnamError;
@@ -15,18 +17,21 @@ use tokio::sync::mpsc;
 // checksums.
 const Q: usize = 8;
 
+/// Split files into chunks and show their metadata.
 #[derive(Debug, StructOpt)]
 pub struct Chunkify {
+    /// Names of files to split into chunks.
     filenames: Vec<PathBuf>,
 }
 
 impl Chunkify {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let rt = Runtime::new()?;
         rt.block_on(self.run_async(config))
     }
 
-    pub async fn run_async(&self, config: &ClientConfig) -> Result<(), ObnamError> {
+    async fn run_async(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let mut q = WorkQueue::new(Q);
         for filename in self.filenames.iter() {
             tokio::spawn(split_file(
@@ -51,21 +56,21 @@ impl Chunkify {
 }
 
 #[derive(Debug, Clone)]
-pub struct Chunk {
+struct Chunk {
     filename: PathBuf,
     offset: u64,
     data: Vec<u8>,
 }
 
 #[derive(Debug, Clone, Serialize)]
-pub struct Checksum {
+struct Checksum {
     filename: PathBuf,
     offset: u64,
     pub len: u64,
     checksum: String,
 }
 
-pub async fn split_file(filename: PathBuf, chunk_size: usize, tx: mpsc::Sender<Chunk>) {
+async fn split_file(filename: PathBuf, chunk_size: usize, tx: mpsc::Sender<Chunk>) {
     // println!("split_file {}", filename.display());
     let mut file = BufReader::new(File::open(&*filename).await.unwrap());
 
diff --git a/src/cmd/gen_info.rs b/src/cmd/gen_info.rs
index 6d12bd8..2663d9b 100644
--- a/src/cmd/gen_info.rs
+++ b/src/cmd/gen_info.rs
@@ -1,3 +1,5 @@
+//! The `gen-info` subcommand.
+
 use crate::client::AsyncBackupClient;
 use crate::config::ClientConfig;
 use crate::error::ObnamError;
@@ -6,13 +8,16 @@ use structopt::StructOpt;
 use tempfile::NamedTempFile;
 use tokio::runtime::Runtime;
 
+/// Show metadata for a generation.
 #[derive(Debug, StructOpt)]
 pub struct GenInfo {
+    /// Reference of the generation.
     #[structopt()]
     gen_ref: String,
 }
 
 impl GenInfo {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let rt = Runtime::new()?;
         rt.block_on(self.run_async(config))
diff --git a/src/cmd/get_chunk.rs b/src/cmd/get_chunk.rs
index f574c99..905e997 100644
--- a/src/cmd/get_chunk.rs
+++ b/src/cmd/get_chunk.rs
@@ -1,3 +1,5 @@
+//! The `get-chunk` subcommand.
+
 use crate::chunkid::ChunkId;
 use crate::client::AsyncBackupClient;
 use crate::config::ClientConfig;
@@ -6,13 +8,16 @@ use std::io::{stdout, Write};
 use structopt::StructOpt;
 use tokio::runtime::Runtime;
 
+/// Fetch a chunk from the server.
 #[derive(Debug, StructOpt)]
 pub struct GetChunk {
+    /// Identifier of chunk to fetch.
     #[structopt()]
     chunk_id: String,
 }
 
 impl GetChunk {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let rt = Runtime::new()?;
         rt.block_on(self.run_async(config))
diff --git a/src/cmd/init.rs b/src/cmd/init.rs
index 08060f7..8e555ca 100644
--- a/src/cmd/init.rs
+++ b/src/cmd/init.rs
@@ -1,3 +1,5 @@
+//! The `init` subcommand.
+
 use crate::config::ClientConfig;
 use crate::error::ObnamError;
 use crate::passwords::{passwords_filename, Passwords};
@@ -5,13 +7,16 @@ use structopt::StructOpt;
 
 const PROMPT: &str = "Obnam passphrase: ";
 
+/// Initialize client by setting passwords.
 #[derive(Debug, StructOpt)]
 pub struct Init {
+    /// Only for testing.
     #[structopt(long)]
     insecure_passphrase: Option<String>,
 }
 
 impl Init {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let passphrase = match &self.insecure_passphrase {
             Some(x) => x.to_string(),
diff --git a/src/cmd/list.rs b/src/cmd/list.rs
index 691f2bf..6c58e30 100644
--- a/src/cmd/list.rs
+++ b/src/cmd/list.rs
@@ -1,13 +1,17 @@
+//! The `list` subcommand.
+
 use crate::client::AsyncBackupClient;
 use crate::config::ClientConfig;
 use crate::error::ObnamError;
 use structopt::StructOpt;
 use tokio::runtime::Runtime;
 
+/// List generations on the server.
 #[derive(Debug, StructOpt)]
 pub struct List {}
 
 impl List {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let rt = Runtime::new()?;
         rt.block_on(self.run_async(config))
diff --git a/src/cmd/list_files.rs b/src/cmd/list_files.rs
index bdec55b..888943e 100644
--- a/src/cmd/list_files.rs
+++ b/src/cmd/list_files.rs
@@ -1,3 +1,5 @@
+//! The `list-files` subcommand.
+
 use crate::backup_reason::Reason;
 use crate::client::AsyncBackupClient;
 use crate::config::ClientConfig;
@@ -7,13 +9,16 @@ use structopt::StructOpt;
 use tempfile::NamedTempFile;
 use tokio::runtime::Runtime;
 
+/// List files in a backup.
 #[derive(Debug, StructOpt)]
 pub struct ListFiles {
+    /// Reference to backup to list files in.
     #[structopt(default_value = "latest")]
     gen_id: String,
 }
 
 impl ListFiles {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let rt = Runtime::new()?;
         rt.block_on(self.run_async(config))
diff --git a/src/cmd/mod.rs b/src/cmd/mod.rs
index ee5efd9..5e5226f 100644
--- a/src/cmd/mod.rs
+++ b/src/cmd/mod.rs
@@ -1,3 +1,5 @@
+//! Subcommand implementations.
+
 pub mod backup;
 pub mod chunk;
 pub mod chunkify;
diff --git a/src/cmd/resolve.rs b/src/cmd/resolve.rs
index 9b36445..cd08908 100644
--- a/src/cmd/resolve.rs
+++ b/src/cmd/resolve.rs
@@ -1,15 +1,20 @@
+//! The `resolve` subcommand.
+
 use crate::client::AsyncBackupClient;
 use crate::config::ClientConfig;
 use crate::error::ObnamError;
 use structopt::StructOpt;
 use tokio::runtime::Runtime;
 
+/// Resolve a generation reference into a generation id.
 #[derive(Debug, StructOpt)]
 pub struct Resolve {
+    /// The generation reference.
     generation: String,
 }
 
 impl Resolve {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let rt = Runtime::new()?;
         rt.block_on(self.run_async(config))
diff --git a/src/cmd/restore.rs b/src/cmd/restore.rs
index 9848caf..2a36986 100644
--- a/src/cmd/restore.rs
+++ b/src/cmd/restore.rs
@@ -1,3 +1,5 @@
+//! The `restore` subcommand.
+
 use crate::backup_reason::Reason;
 use crate::client::{AsyncBackupClient, ClientError};
 use crate::config::ClientConfig;
@@ -19,16 +21,20 @@ use structopt::StructOpt;
 use tempfile::NamedTempFile;
 use tokio::runtime::Runtime;
 
+/// Restore a backup.
 #[derive(Debug, StructOpt)]
 pub struct Restore {
+    /// Reference to generation to restore.
     #[structopt()]
     gen_id: String,
 
+    /// Path to directory where restored files are written.
     #[structopt(parse(from_os_str))]
     to: PathBuf,
 }
 
 impl Restore {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let rt = Runtime::new()?;
         rt.block_on(self.run_async(config))
@@ -75,38 +81,50 @@ impl Restore {
     }
 }
 
+/// Possible errors from restoring.
 #[derive(Debug, thiserror::Error)]
 pub enum RestoreError {
+    /// Failed to create a name pipe.
     #[error("Could not create named pipe (FIFO) {0}")]
     NamedPipeCreationError(PathBuf),
 
+    /// Error from HTTP client.
     #[error(transparent)]
     ClientError(#[from] ClientError),
 
+    /// Error from local generation.
     #[error(transparent)]
     LocalGenerationError(#[from] LocalGenerationError),
 
+    /// Error removing a prefix.
     #[error(transparent)]
     StripPrefixError(#[from] StripPrefixError),
 
+    /// Error creating a directory.
     #[error("failed to create directory {0}: {1}")]
     CreateDirs(PathBuf, std::io::Error),
 
+    /// Error creating a file.
     #[error("failed to create file {0}: {1}")]
     CreateFile(PathBuf, std::io::Error),
 
+    /// Error writing a file.
     #[error("failed to write file {0}: {1}")]
     WriteFile(PathBuf, std::io::Error),
 
+    /// Error creating a symbolic link.
     #[error("failed to create symbolic link {0}: {1}")]
     Symlink(PathBuf, std::io::Error),
 
+    /// Error creating a UNIX domain socket.
     #[error("failed to create UNIX domain socket {0}: {1}")]
     UnixBind(PathBuf, std::io::Error),
 
+    /// Error setting permissions.
     #[error("failed to set permissions for {0}: {1}")]
     Chmod(PathBuf, std::io::Error),
 
+    /// Error settting timestamp.
     #[error("failed to set timestamp for {0}: {1}")]
     SetTimestamp(PathBuf, std::io::Error),
 }
diff --git a/src/cmd/show_config.rs b/src/cmd/show_config.rs
index 05e83c1..7ac52ec 100644
--- a/src/cmd/show_config.rs
+++ b/src/cmd/show_config.rs
@@ -1,11 +1,15 @@
+//! The `show-config` subcommand.
+
 use crate::config::ClientConfig;
 use crate::error::ObnamError;
 use structopt::StructOpt;
 
+/// Show actual client configuration.
 #[derive(Debug, StructOpt)]
 pub struct ShowConfig {}
 
 impl ShowConfig {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         println!("{}", serde_json::to_string_pretty(config)?);
         Ok(())
diff --git a/src/cmd/show_gen.rs b/src/cmd/show_gen.rs
index fb7e1bd..6ec1203 100644
--- a/src/cmd/show_gen.rs
+++ b/src/cmd/show_gen.rs
@@ -1,3 +1,5 @@
+//! The `show-generation` subcommand.
+
 use crate::client::AsyncBackupClient;
 use crate::config::ClientConfig;
 use crate::error::ObnamError;
@@ -7,13 +9,16 @@ use structopt::StructOpt;
 use tempfile::NamedTempFile;
 use tokio::runtime::Runtime;
 
+/// Show information about a generation.
 #[derive(Debug, StructOpt)]
 pub struct ShowGeneration {
+    /// Reference to the generation. Defaults to latest.
     #[structopt(default_value = "latest")]
     gen_id: String,
 }
 
 impl ShowGeneration {
+    /// Run the command.
     pub fn run(&self, config: &ClientConfig) -> Result<(), ObnamError> {
         let rt = Runtime::new()?;
         rt.block_on(self.run_async(config))