clean doc

src/account/arg/name.rs

@@ -1,26 +1,24 @@
 use clap::Parser;
 
-/// The account name argument parser
+/// The account name argument parser.
 #[derive(Debug, Parser)]
 pub struct AccountNameArg {
-    /// The name of the account
+    /// The name of the account.
     ///
-    /// The account names are taken from the table at the root level
-    /// of your TOML configuration file.
-    #[arg(value_name = "ACCOUNT")]
+    /// An account name corresponds to an entry in the table at the
+    /// root level of your TOML configuration file.
+    #[arg(name = "account_name", value_name = "ACCOUNT")]
     pub name: String,
 }
 
-/// The account name flag parser
+/// The account name flag parser.
 #[derive(Debug, Parser)]
 pub struct AccountNameFlag {
-    /// Override the default account
-    #[arg(
-        long = "account",
-        short = 'a',
-        name = "account-name",
-        value_name = "NAME",
-        global = true
-    )]
+    /// Override the default account.
+    ///
+    /// An account name corresponds to an entry in the table at the
+    /// root level of your TOML configuration file.
+    #[arg(long = "account", short = 'a', global = true)]
+    #[arg(name = "account_name", value_name = "NAME")]
     pub name: Option<String>,
 }

src/account/command/configure.rs

@@ -15,26 +15,32 @@ use crate::{
     printer::Printer,
 };
 
-/// Configure the given account
+/// Configure an account.
+///
+/// This command is mostly used to define or reset passwords managed
+/// by your global keyring. If you do not use the keyring system, you
+/// can skip this command.
 #[derive(Debug, Parser)]
 pub struct AccountConfigureCommand {
     #[command(flatten)]
     pub account: AccountNameArg,
 
-    /// Force the account to reconfigure, even if it has already been
-    /// configured
+    /// Reset keyring passwords.
+    ///
+    /// This argument will force passwords to be prompted again, then
+    /// saved to your global keyring.
     #[arg(long, short)]
-    pub force: bool,
+    pub reset: bool,
 }
 
 impl AccountConfigureCommand {
     pub async fn execute(self, printer: &mut impl Printer, config: &TomlConfig) -> Result<()> {
         info!("executing account configure command");
 
-        let (_, account_config) =
-            config.into_toml_account_config(Some(self.account.name.as_str()))?;
+        let account = &self.account.name;
+        let (_, account_config) = config.into_toml_account_config(Some(account))?;
 
-        if self.force {
+        if self.reset {
             #[cfg(feature = "imap")]
             if let Some(ref config) = account_config.imap {
                 let reset = match &config.auth {
@@ -102,11 +108,8 @@ impl AccountConfigureCommand {
         }
 
         printer.print(format!(
-            "Account {} successfully {}configured!",
-            self.account.name,
-            if self.force { "re" } else { "" }
-        ))?;
-
-        Ok(())
+            "Account {account} successfully {}configured!",
+            if self.reset { "re" } else { "" }
+        ))
     }
 }

src/account/command/list.rs

@@ -6,14 +6,17 @@ use crate::{
     account::Accounts,
     config::TomlConfig,
     printer::{PrintTableOpts, Printer},
-    ui::arg::max_width::MaxTableWidthFlag,
+    ui::arg::max_width::TableMaxWidthFlag,
 };
 
-/// List all accounts
+/// List all accounts.
+///
+/// This command lists all accounts defined in your TOML configuration
+/// file.
 #[derive(Debug, Parser)]
 pub struct AccountListCommand {
     #[command(flatten)]
-    pub table: MaxTableWidthFlag,
+    pub table: TableMaxWidthFlag,
 }
 
 impl AccountListCommand {
@@ -31,9 +34,7 @@ impl AccountListCommand {
                     .unwrap_or(&Default::default()),
                 max_width: self.table.max_width,
             },
-        )?;
-
-        Ok(())
+        )
     }
 }
 

src/account/command/mod.rs

@@ -11,18 +11,19 @@ use self::{
     configure::AccountConfigureCommand, list::AccountListCommand, sync::AccountSyncCommand,
 };
 
-/// Subcommand to manage accounts
+/// Manage accounts.
+///
+/// An account is a set of settings, identified by an account
+/// name. Settings are directly taken from your TOML configuration
+/// file.
 #[derive(Debug, Subcommand)]
 pub enum AccountSubcommand {
-    /// Configure an account
     #[command(alias = "cfg")]
     Configure(AccountConfigureCommand),
 
-    /// List all accounts
     #[command(alias = "lst")]
     List(AccountListCommand),
 
-    /// Synchronize an account locally
     #[command()]
     Sync(AccountSyncCommand),
 }

src/account/command/sync.rs

@@ -32,30 +32,49 @@ const SUB_PROGRESS_DONE_STYLE: Lazy<ProgressStyle> = Lazy::new(|| {
     ProgressStyle::with_template("   {prefix:.bold} \n   {wide_bar:.green} {percent}% ").unwrap()
 });
 
+/// Synchronize an account.
+///
+/// This command allows you to synchronize all folders and emails
+/// (including envelopes and messages) of an account into a local
+/// Maildir folder.
 #[derive(Debug, Parser)]
 pub struct AccountSyncCommand {
     #[command(flatten)]
     pub account: AccountNameArg,
 
-    /// Run the synchronization without applying changes
+    /// Run the synchronization without applying any changes.
     ///
     /// Instead, a report will be printed to stdout containing all the
     /// changes the synchronization plan to do.
     #[arg(long, short)]
     pub dry_run: bool,
 
-    #[arg(long, short = 'f', value_name = "FOLDER", action = ArgAction::Append, conflicts_with = "exclude_folder", conflicts_with = "all_folders")]
+    /// Synchronize only specific folders.
+    ///
+    /// Only the given folders will be synchronized (including
+    /// associated envelopes and messages). Useful when you need to
+    /// speed up the synchronization process. A good usecase is to
+    /// synchronize only the INBOX in order to quickly check for new
+    /// messages.
+    #[arg(long, short = 'f')]
+    #[arg(value_name = "FOLDER", action = ArgAction::Append)]
+    #[arg(conflicts_with = "exclude_folder", conflicts_with = "all_folders")]
     pub include_folder: Vec<String>,
 
-    #[arg(long, short = 'x', value_name = "FOLDER", action = ArgAction::Append, conflicts_with = "include_folder", conflicts_with = "all_folders")]
+    /// Omit specific folders from the synchronization.
+    ///
+    /// The given folders will be excluded from the synchronization
+    /// (including associated envelopes and messages). Useful when you
+    /// have heavy folders that you do not want to take care of, or to
+    /// speed up the synchronization process.
+    #[arg(long, short = 'x')]
+    #[arg(value_name = "FOLDER", action = ArgAction::Append)]
+    #[arg(conflicts_with = "include_folder", conflicts_with = "all_folders")]
     pub exclude_folder: Vec<String>,
 
-    #[arg(
-        long,
-        short = 'A',
-        conflicts_with = "include_folder",
-        conflicts_with = "exclude_folder"
-    )]
+    /// Synchronize all exsting folders.
+    #[arg(long, short = 'A')]
+    #[arg(conflicts_with = "include_folder", conflicts_with = "exclude_folder")]
     pub all_folders: bool,
 }
 

src/cache/arg/disable.rs

@@ -1,19 +1,15 @@
 use clap::Parser;
 
-/// The disable cache flag parser
+/// The disable cache flag parser.
 #[derive(Debug, Parser)]
-pub struct DisableCacheFlag {
-    /// Disable any sort of cache
+pub struct CacheDisableFlag {
+    /// Disable any sort of cache.
     ///
     /// The action depends on commands it apply on. For example, when
     /// listing envelopes using the IMAP backend, this flag will
-    /// ensure that envelopes are fetched from the IMAP server and not
-    /// from the synchronized local Maildir.
-    #[arg(
-        long = "disable-cache",
-        alias = "no-cache",
-        name = "disable-cache",
-        global = true
-    )]
+    /// ensure that envelopes are fetched from the IMAP server rather
+    /// than the synchronized local Maildir.
+    #[arg(long = "disable-cache", alias = "no-cache", global = true)]
+    #[arg(name = "cache_disable")]
     pub disable: bool,
 }

src/cli.rs

@@ -19,14 +19,8 @@ use crate::{
 };
 
 #[derive(Parser, Debug)]
-#[command(
-    name = "himalaya",
-    author,
-    version,
-    about,
-    propagate_version = true,
-    infer_subcommands = true
-)]
+#[command(name = "himalaya", author, version, about)]
+#[command(propagate_version = true, infer_subcommands = true)]
 pub struct Cli {
     #[command(subcommand)]
     pub command: HimalayaCommand,
@@ -83,46 +77,38 @@ pub struct Cli {
 
 #[derive(Subcommand, Debug)]
 pub enum HimalayaCommand {
-    /// Manage accounts
     #[command(subcommand)]
     #[command(alias = "accounts")]
     Account(AccountSubcommand),
 
-    /// Manage folders
     #[command(subcommand)]
     #[command(alias = "folders")]
     Folder(FolderSubcommand),
 
-    /// Manage envelopes
     #[command(subcommand)]
     #[command(alias = "envelopes")]
     Envelope(EnvelopeSubcommand),
 
-    /// Manage flags
     #[command(subcommand)]
     #[command(alias = "flags")]
     Flag(FlagSubcommand),
 
-    /// Manage messages
     #[command(subcommand)]
     #[command(alias = "messages", alias = "msgs", alias = "msg")]
     Message(MessageSubcommand),
 
-    /// Manage templates
     #[command(subcommand)]
-    #[command(alias = "templates", alias = "tpls", alias = "tpl")]
-    Template(TemplateSubcommand),
+    #[command(alias = "attachments")]
+    Attachment(AttachmentSubcommand),
 
-    /// Manage attachments
     #[command(subcommand)]
-    Attachment(AttachmentSubcommand),
+    #[command(alias = "templates", alias = "tpls", alias = "tpl")]
+    Template(TemplateSubcommand),
 
-    /// Generate manual pages to a directory
     #[command(arg_required_else_help = true)]
     #[command(alias = "manuals", alias = "mans")]
     Manual(ManualGenerateCommand),
 
-    /// Print completion script for a shell to stdout
     #[command(arg_required_else_help = true)]
     #[command(alias = "completions")]
     Completion(CompletionGenerateCommand),
@@ -136,8 +122,8 @@ impl HimalayaCommand {
             Self::Envelope(cmd) => cmd.execute(printer, config).await,
             Self::Flag(cmd) => cmd.execute(printer, config).await,
             Self::Message(cmd) => cmd.execute(printer, config).await,
-            Self::Template(cmd) => cmd.execute(printer, config).await,
             Self::Attachment(cmd) => cmd.execute(printer, config).await,
+            Self::Template(cmd) => cmd.execute(printer, config).await,
             Self::Manual(cmd) => cmd.execute(printer).await,
             Self::Completion(cmd) => cmd.execute(printer).await,
         }

src/completion/command.rs

@@ -6,10 +6,14 @@ use std::io;
 
 use crate::{cli::Cli, printer::Printer};
 
-/// Print completion script for a shell to stdout
+/// Print completion script for a shell to stdout.
+///
+/// This command allows you to generate completion script for a given
+/// shell. The script is printed to the standard output. If you want
+/// to write it to a file, just use unix redirection.
 #[derive(Debug, Parser)]
 pub struct CompletionGenerateCommand {
-    /// Shell for which completion script should be generated for
+    /// Shell for which completion script should be generated for.
     #[arg(value_parser = value_parser!(Shell))]
     pub shell: Shell,
 }

src/config/mod.rs

@@ -121,10 +121,7 @@ impl TomlConfig {
         match path.map(Into::into) {
             Some(ref path) if path.exists() => Self::from_path(path),
             Some(path) => Self::from_wizard(path).await,
-            None => match Self::first_valid_default_path() {
-                Some(path) => Self::from_path(&path),
-                None => Self::from_wizard(Self::default_path()?).await,
-            },
+            None => Self::from_default_paths().await,
         }
     }
 

src/email/envelope/arg/ids.rs

@@ -1,17 +1,17 @@
 use clap::Parser;
 
-/// The envelope id argument parser
+/// The envelope id argument parser.
 #[derive(Debug, Parser)]
 pub struct EnvelopeIdArg {
-    /// The envelope id
+    /// The envelope id.
     #[arg(value_name = "ID", required = true)]
     pub id: usize,
 }
 
-/// The envelopes ids arguments parser
+/// The envelopes ids arguments parser.
 #[derive(Debug, Parser)]
 pub struct EnvelopeIdsArgs {
-    /// The list of envelopes ids
+    /// The list of envelopes ids.
     #[arg(value_name = "ID", required = true)]
     pub ids: Vec<usize>,
 }