Removed docs headers

2025-12-07 09:36:00 -08:00 · 2021-12-11 10:19:29 +01:00
parent 2e0322bc0e
commit 027545f14c
52 changed files with 0 additions and 966 deletions
--- a/src/system/auto_update.rs
+++ b/src/system/auto_update.rs
@@ -44,8 +44,6 @@ pub enum UpdateStatus {
    UpdateInstalled(String),
 }

-/// ## Release
-///
 /// Info related to a github release
 #[derive(Debug)]
 pub struct Release {
@@ -53,8 +51,6 @@ pub struct Release {
    pub body: String,
 }

-/// ## Update
-///
 /// The update structure defines the options used to install the update.
 /// Once you're fine with the options, just call the `upgrade()` method to upgrade termscp.
 #[derive(Debug, Default)]
@@ -64,16 +60,12 @@ pub struct Update {
 }

 impl Update {
-    /// ### show_progress
-    ///
    /// Set whether to show or not the progress bar
    pub fn show_progress(mut self, opt: bool) -> Self {
        self.progress = opt;
        self
    }

-    /// ### ask_confirm
-    ///
    /// Set whether to ask for confirm when updating
    pub fn ask_confirm(mut self, opt: bool) -> Self {
        self.ask_confirm = opt;
@@ -96,8 +88,6 @@ impl Update {
            .map(UpdateStatus::from)
    }

-    /// ### is_new_version_available
-    ///
    /// Returns whether a new version of termscp is available
    /// In case of success returns Ok(Option<Release>), where the Option is Some(new_version);
    /// otherwise if no version is available, return None
@@ -119,8 +109,6 @@ impl Update {
            .map(Self::check_version)
    }

-    /// ### check_version
-    ///
    /// In case received version is newer than current one, version as Some is returned; otherwise None
    fn check_version(r: Release) -> Option<Release> {
        match parse_semver(r.version.as_str()) {
--- a/src/system/bookmarks_client.rs
+++ b/src/system/bookmarks_client.rs
@@ -44,8 +44,6 @@ use std::path::{Path, PathBuf};
 use std::string::ToString;
 use std::time::SystemTime;

-/// ## BookmarksClient
-///
 /// BookmarksClient provides a layer between the host system and the bookmarks module
 pub struct BookmarksClient {
    hosts: UserHosts,
@@ -55,8 +53,6 @@ pub struct BookmarksClient {
 }

 impl BookmarksClient {
-    /// ### BookmarksClient
-    ///
    /// Instantiates a new BookmarksClient
    /// Bookmarks file path must be provided
    /// Storage path for file provider must be provided
@@ -155,15 +151,11 @@ impl BookmarksClient {
        Ok(client)
    }

-    /// ### iter_bookmarks
-    ///
    /// Iterate over bookmarks keys
    pub fn iter_bookmarks(&self) -> impl Iterator<Item = &String> + '_ {
        Box::new(self.hosts.bookmarks.keys())
    }

-    /// ### get_bookmark
-    ///
    /// Get bookmark associated to key
    pub fn get_bookmark(&self, key: &str) -> Option<FileTransferParams> {
        debug!("Getting bookmark {}", key);
@@ -183,8 +175,6 @@ impl BookmarksClient {
        Some(FileTransferParams::from(entry))
    }

-    /// ### add_recent
-    ///
    /// Add a new recent to bookmarks
    pub fn add_bookmark<S: AsRef<str>>(
        &mut self,
@@ -207,22 +197,16 @@ impl BookmarksClient {
        self.hosts.bookmarks.insert(name, host);
    }

-    /// ### del_bookmark
-    ///
    /// Delete entry from bookmarks
    pub fn del_bookmark(&mut self, name: &str) {
        let _ = self.hosts.bookmarks.remove(name);
        info!("Removed bookmark {}", name);
    }
-    /// ### iter_recents
-    ///
    /// Iterate over recents keys
    pub fn iter_recents(&self) -> impl Iterator<Item = &String> + '_ {
        Box::new(self.hosts.recents.keys())
    }

-    /// ### get_recent
-    ///
    /// Get recent associated to key
    pub fn get_recent(&self, key: &str) -> Option<FileTransferParams> {
        // NOTE: password is not decrypted; recents will never have password
@@ -231,8 +215,6 @@ impl BookmarksClient {
        Some(FileTransferParams::from(entry))
    }

-    /// ### add_recent
-    ///
    /// Add a new recent to bookmarks
    pub fn add_recent(&mut self, params: FileTransferParams) {
        // Make bookmark
@@ -271,16 +253,12 @@ impl BookmarksClient {
        self.hosts.recents.insert(name, host);
    }

-    /// ### del_recent
-    ///
    /// Delete entry from recents
    pub fn del_recent(&mut self, name: &str) {
        let _ = self.hosts.recents.remove(name);
        info!("Removed recent host {}", name);
    }

-    /// ### write_bookmarks
-    ///
    /// Write bookmarks to file
    pub fn write_bookmarks(&self) -> Result<(), SerializerError> {
        // Open file
@@ -302,8 +280,6 @@ impl BookmarksClient {
        }
    }

-    /// ### read_bookmarks
-    ///
    /// Read bookmarks from file
    fn read_bookmarks(&mut self) -> Result<(), SerializerError> {
        // Open bookmarks file for read
@@ -332,16 +308,12 @@ impl BookmarksClient {
        }
    }

-    /// ### generate_key
-    ///
    /// Generate a new AES key
    fn generate_key() -> String {
        // Generate 256 bytes (2048 bits) key
        random_alphanumeric_with_len(256)
    }

-    /// ### make_bookmark
-    ///
    /// Make bookmark from credentials
    fn make_bookmark(&self, params: FileTransferParams) -> Bookmark {
        let mut bookmark: Bookmark = Bookmark::from(params);
@@ -352,15 +324,11 @@ impl BookmarksClient {
        bookmark
    }

-    /// ### encrypt_str
-    ///
    /// Encrypt provided string using AES-128. Encrypted buffer is then converted to BASE64
    fn encrypt_str(&self, txt: &str) -> String {
        crypto::aes128_b64_crypt(self.key.as_str(), txt)
    }

-    /// ### decrypt_str
-    ///
    /// Decrypt provided string using AES-128
    fn decrypt_str(&self, secret: &str) -> Result<String, SerializerError> {
        match crypto::aes128_b64_decrypt(self.key.as_str(), secret) {
@@ -741,8 +709,6 @@ mod tests {
        assert!(client.decrypt_str("bidoof").is_err());
    }

-    /// ### get_paths
-    ///
    /// Get paths for configuration and key for bookmarks
    fn get_paths(dir: &Path) -> (PathBuf, PathBuf) {
        let k: PathBuf = PathBuf::from(dir);
--- a/src/system/config_client.rs
+++ b/src/system/config_client.rs
@@ -42,8 +42,6 @@ use std::string::ToString;
 // Types
 pub type SshHost = (String, String, PathBuf); // 0: host, 1: username, 2: RSA key path

-/// ## ConfigClient
-///
 /// ConfigClient provides a high level API to communicate with the termscp configuration
 pub struct ConfigClient {
    config: UserConfig,   // Configuration loaded
@@ -53,8 +51,6 @@ pub struct ConfigClient {
 }

 impl ConfigClient {
-    /// ### new
-    ///
    /// Instantiate a new `ConfigClient` with provided path
    pub fn new(config_path: &Path, ssh_key_dir: &Path) -> Result<Self, SerializerError> {
        // Initialize a default configuration
@@ -104,8 +100,6 @@ impl ConfigClient {
        Ok(client)
    }

-    /// ### degraded
-    ///
    /// Instantiate a ConfigClient in degraded mode.
    /// When in degraded mode, the configuration in use will be the default configuration
    /// and the IO operation on configuration won't be available
@@ -120,15 +114,11 @@ impl ConfigClient {

    // Text editor

-    /// ### get_text_editor
-    ///
    /// Get text editor from configuration
    pub fn get_text_editor(&self) -> PathBuf {
        self.config.user_interface.text_editor.clone()
    }

-    /// ### set_text_editor
-    ///
    /// Set text editor path
    pub fn set_text_editor(&mut self, path: PathBuf) {
        self.config.user_interface.text_editor = path;
@@ -136,8 +126,6 @@ impl ConfigClient {

    // Default protocol

-    /// ### get_default_protocol
-    ///
    /// Get default protocol from configuration
    pub fn get_default_protocol(&self) -> FileTransferProtocol {
        match FileTransferProtocol::from_str(self.config.user_interface.default_protocol.as_str()) {
@@ -146,43 +134,31 @@ impl ConfigClient {
        }
    }

-    /// ### set_default_protocol
-    ///
    /// Set default protocol to configuration
    pub fn set_default_protocol(&mut self, proto: FileTransferProtocol) {
        self.config.user_interface.default_protocol = proto.to_string();
    }

-    /// ### get_show_hidden_files
-    ///
    /// Get value of `show_hidden_files`
    pub fn get_show_hidden_files(&self) -> bool {
        self.config.user_interface.show_hidden_files
    }

-    /// ### set_show_hidden_files
-    ///
    /// Set new value for `show_hidden_files`
    pub fn set_show_hidden_files(&mut self, value: bool) {
        self.config.user_interface.show_hidden_files = value;
    }

-    /// ### get_check_for_updates
-    ///
    /// Get value of `check_for_updates`
    pub fn get_check_for_updates(&self) -> bool {
        self.config.user_interface.check_for_updates.unwrap_or(true)
    }

-    /// ### set_check_for_updates
-    ///
    /// Set new value for `check_for_updates`
    pub fn set_check_for_updates(&mut self, value: bool) {
        self.config.user_interface.check_for_updates = Some(value);
    }

-    /// ### get_prompt_on_file_replace
-    ///
    /// Get value of `prompt_on_file_replace`
    pub fn get_prompt_on_file_replace(&self) -> bool {
        self.config
@@ -191,15 +167,11 @@ impl ConfigClient {
            .unwrap_or(true)
    }

-    /// ### set_prompt_on_file_replace
-    ///
    /// Set new value for `prompt_on_file_replace`
    pub fn set_prompt_on_file_replace(&mut self, value: bool) {
        self.config.user_interface.prompt_on_file_replace = Some(value);
    }

-    /// ### get_group_dirs
-    ///
    /// Get GroupDirs value from configuration (will be converted from string)
    pub fn get_group_dirs(&self) -> Option<GroupDirs> {
        // Convert string to `GroupDirs`
@@ -212,23 +184,17 @@ impl ConfigClient {
        }
    }

-    /// ### set_group_dirs
-    ///
    /// Set value for group_dir in configuration.
    /// Provided value, if `Some` will be converted to `GroupDirs`
    pub fn set_group_dirs(&mut self, val: Option<GroupDirs>) {
        self.config.user_interface.group_dirs = val.map(|val| val.to_string());
    }

-    /// ### get_local_file_fmt
-    ///
    /// Get current file fmt for local host
    pub fn get_local_file_fmt(&self) -> Option<String> {
        self.config.user_interface.file_fmt.clone()
    }

-    /// ### set_local_file_fmt
-    ///
    /// Set file fmt parameter for local host
    pub fn set_local_file_fmt(&mut self, s: String) {
        self.config.user_interface.file_fmt = match s.is_empty() {
@@ -237,15 +203,11 @@ impl ConfigClient {
        };
    }

-    /// ### get_remote_file_fmt
-    ///
    /// Get current file fmt for remote host
    pub fn get_remote_file_fmt(&self) -> Option<String> {
        self.config.user_interface.remote_file_fmt.clone()
    }

-    /// ### set_remote_file_fmt
-    ///
    /// Set file fmt parameter for remote host
    pub fn set_remote_file_fmt(&mut self, s: String) {
        self.config.user_interface.remote_file_fmt = match s.is_empty() {
@@ -254,22 +216,16 @@ impl ConfigClient {
        };
    }

-    /// ### get_notifications
-    ///
    /// Get value of `notifications`
    pub fn get_notifications(&self) -> bool {
        self.config.user_interface.notifications.unwrap_or(true)
    }

-    /// ### set_notifications
-    ///
    /// Set new value for `notifications`
    pub fn set_notifications(&mut self, value: bool) {
        self.config.user_interface.notifications = Some(value);
    }

-    /// ### get_notification_threshold
-    ///
    /// Get value of `notification_threshold`
    pub fn get_notification_threshold(&self) -> u64 {
        self.config
@@ -278,8 +234,6 @@ impl ConfigClient {
            .unwrap_or(DEFAULT_NOTIFICATION_TRANSFER_THRESHOLD)
    }

-    /// ### set_notification_threshold
-    ///
    /// Set new value for `notification_threshold`
    pub fn set_notification_threshold(&mut self, value: u64) {
        self.config.user_interface.notification_threshold = Some(value);
@@ -287,8 +241,6 @@ impl ConfigClient {

    // SSH Keys

-    /// ### save_ssh_key
-    ///
    /// Save a SSH key into configuration.
    /// This operation also creates the key file in `ssh_key_dir`
    /// and also commits changes to configuration, to prevent incoerent data
@@ -331,8 +283,6 @@ impl ConfigClient {
        self.write_config()
    }

-    /// ### del_ssh_key
-    ///
    /// Delete a ssh key from configuration, using host as key.
    /// This operation also unlinks the key file in `ssh_key_dir`
    /// and also commits changes to configuration, to prevent incoerent data
@@ -363,8 +313,6 @@ impl ConfigClient {
        self.write_config()
    }

-    /// ### get_ssh_key
-    ///
    /// Get ssh key from host.
    /// None is returned if key doesn't exist
    /// `std::io::Error` is returned in case it was not possible to read the key file
@@ -384,8 +332,6 @@ impl ConfigClient {
        }
    }

-    /// ### iter_ssh_keys
-    ///
    /// Get an iterator through hosts in the ssh key storage
    pub fn iter_ssh_keys(&self) -> impl Iterator<Item = &String> + '_ {
        Box::new(self.config.remote.ssh_keys.keys())
@@ -393,8 +339,6 @@ impl ConfigClient {

    // I/O

-    /// ### write_config
-    ///
    /// Write configuration to file
    pub fn write_config(&self) -> Result<(), SerializerError> {
        if self.degraded {
@@ -421,8 +365,6 @@ impl ConfigClient {
        }
    }

-    /// ### read_config
-    ///
    /// Read configuration from file (or reload it if already read)
    pub fn read_config(&mut self) -> Result<(), SerializerError> {
        if self.degraded {
@@ -456,16 +398,12 @@ impl ConfigClient {
        }
    }

-    /// ### make_ssh_host_key
-    ///
    /// Hosts are saved as `username@host` into configuration.
    /// This method creates the key name, starting from host and username
    fn make_ssh_host_key(host: &str, username: &str) -> String {
        format!("{}@{}", username, host)
    }

-    /// ### get_ssh_tokens
-    ///
    /// Get ssh tokens starting from ssh host key
    /// Panics if key has invalid syntax
    /// Returns: (host, username)
@@ -475,8 +413,6 @@ impl ConfigClient {
        (String::from(tokens[1]), String::from(tokens[0]))
    }

-    /// ### make_io_err
-    ///
    /// Make serializer error from `std::io::Error`
    fn make_io_err(err: std::io::Error) -> Result<(), SerializerError> {
        Err(SerializerError::new_ex(
@@ -774,8 +710,6 @@ mod tests {
        assert_eq!(err.to_string(), "IO error (permission denied)");
    }

-    /// ### get_paths
-    ///
    /// Get paths for configuration and keys directory
    fn get_paths(dir: &Path) -> (PathBuf, PathBuf) {
        let mut k: PathBuf = PathBuf::from(dir);
--- a/src/system/keys/filestorage.rs
+++ b/src/system/keys/filestorage.rs
@@ -32,16 +32,12 @@ use std::fs::{OpenOptions, Permissions};
 use std::io::{Read, Write};
 use std::path::{Path, PathBuf};

-/// ## FileStorage
-///
 /// File storage is an implementation o the `KeyStorage` which uses a file to store the key
 pub struct FileStorage {
    dir_path: PathBuf,
 }

 impl FileStorage {
-    /// ### new
-    ///
    /// Instantiates a new `FileStorage`
    pub fn new(dir_path: &Path) -> Self {
        FileStorage {
@@ -49,8 +45,6 @@ impl FileStorage {
        }
    }

-    /// ### make_file_path
-    ///
    /// Make file path for key file from `dir_path` and the application id
    fn make_file_path(&self, storage_id: &str) -> PathBuf {
        let mut p: PathBuf = self.dir_path.clone();
@@ -61,8 +55,6 @@ impl FileStorage {
 }

 impl KeyStorage for FileStorage {
-    /// ### get_key
-    ///
    /// Retrieve key from the key storage.
    /// The key might be acccess through an identifier, which identifies
    /// the key in the storage
@@ -85,8 +77,6 @@ impl KeyStorage for FileStorage {
        }
    }

-    /// ### set_key
-    ///
    /// Set the key into the key storage
    fn set_key(&self, storage_id: &str, key: &str) -> Result<(), KeyStorageError> {
        let key_file: PathBuf = self.make_file_path(storage_id);
--- a/src/system/keys/keyringstorage.rs
+++ b/src/system/keys/keyringstorage.rs
@@ -30,16 +30,12 @@ use super::{KeyStorage, KeyStorageError};
 // Ext
 use keyring::{Keyring, KeyringError};

-/// ## KeyringStorage
-///
 /// provides a `KeyStorage` implementation using the keyring crate
 pub struct KeyringStorage {
    username: String,
 }

 impl KeyringStorage {
-    /// ### new
-    ///
    /// Instantiates a new KeyringStorage
    pub fn new(username: &str) -> Self {
        KeyringStorage {
@@ -49,8 +45,6 @@ impl KeyringStorage {
 }

 impl KeyStorage for KeyringStorage {
-    /// ### get_key
-    ///
    /// Retrieve key from the key storage.
    /// The key might be acccess through an identifier, which identifies
    /// the key in the storage
@@ -72,8 +66,6 @@ impl KeyStorage for KeyringStorage {
        }
    }

-    /// ### set_key
-    ///
    /// Set the key into the key storage
    fn set_key(&self, storage_id: &str, key: &str) -> Result<(), KeyStorageError> {
        let storage: Keyring = Keyring::new(storage_id, self.username.as_str());
--- a/src/system/keys/mod.rs
+++ b/src/system/keys/mod.rs
@@ -32,8 +32,6 @@ pub mod keyringstorage;
 // ext
 use thiserror::Error;

-/// ## KeyStorageError
-///
 /// defines the error type for the `KeyStorage`
 #[derive(Debug, Error, PartialEq)]
 pub enum KeyStorageError {
@@ -46,19 +44,13 @@ pub enum KeyStorageError {
    NoSuchKey,
 }

-/// ## KeyStorage
-///
 /// this traits provides the methods to communicate and interact with the key storage.
 pub trait KeyStorage {
-    /// ### get_key
-    ///
    /// Retrieve key from the key storage.
    /// The key might be acccess through an identifier, which identifies
    /// the key in the storage
    fn get_key(&self, storage_id: &str) -> Result<String, KeyStorageError>;

-    /// ### set_key
-    ///
    /// Set the key into the key storage
    fn set_key(&self, storage_id: &str, key: &str) -> Result<(), KeyStorageError>;

--- a/src/system/notifications.rs
+++ b/src/system/notifications.rs
@@ -6,14 +6,10 @@
 use notify_rust::Hint;
 use notify_rust::{Notification as OsNotification, Timeout};

-/// ## Notification
-///
 /// A notification helper which provides all the functions to send the available notifications for termscp
 pub struct Notification;

 impl Notification {
-    /// ### transfer_completed
-    ///
    /// Notify a transfer has been completed with success
    pub fn transfer_completed<S: AsRef<str>>(body: S) {
        Self::notify(
@@ -23,15 +19,11 @@ impl Notification {
        );
    }

-    /// ### transfer_error
-    ///
    /// Notify a transfer has failed
    pub fn transfer_error<S: AsRef<str>>(body: S) {
        Self::notify("Transfer failed ❌", body.as_ref(), Some("transfer.error"));
    }

-    /// ### update_available
-    ///
    /// Notify a new version of termscp is available for download
    pub fn update_available<S: AsRef<str>>(version: S) {
        Self::notify(
@@ -41,8 +33,6 @@ impl Notification {
        );
    }

-    /// ### update_installed
-    ///
    /// Notify the update has been correctly installed
    pub fn update_installed<S: AsRef<str>>(version: S) {
        Self::notify(
@@ -52,15 +42,11 @@ impl Notification {
        );
    }

-    /// ### update_failed
-    ///
    /// Notify the update installation has failed
    pub fn update_failed<S: AsRef<str>>(err: S) {
        Self::notify("Update installation failed ❌", err.as_ref(), None);
    }

-    /// ### notify
-    ///
    /// Notify guest OS with provided Summary, body and optional category
    /// e.g. Category is supported on FreeBSD/Linux only
    #[allow(unused_variables)]
--- a/src/system/sshkey_storage.rs
+++ b/src/system/sshkey_storage.rs
@@ -37,8 +37,6 @@ pub struct SshKeyStorage {
 }

 impl SshKeyStorage {
-    /// ### storage_from_config
-    ///
    /// Create a `SshKeyStorage` starting from a `ConfigClient`
    pub fn storage_from_config(cfg_client: &ConfigClient) -> Self {
        let mut hosts: HashMap<String, PathBuf> =
@@ -65,8 +63,6 @@ impl SshKeyStorage {
        SshKeyStorage { hosts }
    }

-    /// ### empty
-    ///
    /// Create an empty ssh key storage; used in case `ConfigClient` is not available
    #[cfg(test)]
    pub fn empty() -> Self {
@@ -75,16 +71,12 @@ impl SshKeyStorage {
        }
    }

-    /// ### make_mapkey
-    ///
    /// Make mapkey from host and username
    fn make_mapkey(host: &str, username: &str) -> String {
        format!("{}@{}", username, host)
    }

    #[cfg(test)]
-    /// ### add_key
-    ///
    /// Add a key to storage
    /// NOTE: available only for tests
    pub fn add_key(&mut self, host: &str, username: &str, p: PathBuf) {
@@ -149,8 +141,6 @@ mod tests {
        );
    }

-    /// ### get_paths
-    ///
    /// Get paths for configuration and keys directory
    fn get_paths(dir: &Path) -> (PathBuf, PathBuf) {
        let mut k: PathBuf = PathBuf::from(dir);
--- a/src/system/theme_provider.rs
+++ b/src/system/theme_provider.rs
@@ -35,8 +35,6 @@ use std::fs::OpenOptions;
 use std::path::{Path, PathBuf};
 use std::string::ToString;

-/// ## ThemeProvider
-///
 /// ThemeProvider provides a high level API to communicate with the termscp theme
 pub struct ThemeProvider {
    theme: Theme,        // Theme loaded
@@ -45,8 +43,6 @@ pub struct ThemeProvider {
 }

 impl ThemeProvider {
-    /// ### new
-    ///
    /// Instantiates a new `ThemeProvider`
    pub fn new(theme_path: &Path) -> Result<Self, SerializerError> {
        let default_theme: Theme = Theme::default();
@@ -78,8 +74,6 @@ impl ThemeProvider {
        Ok(provider)
    }

-    /// ### degraded
-    ///
    /// Create a new theme provider which won't work with file system.
    /// This is done in order to prevent a lot of `unwrap_or` on Ui
    pub fn degraded() -> Self {
@@ -92,15 +86,11 @@ impl ThemeProvider {

    // -- getters

-    /// ### theme
-    ///
    /// Returns theme as reference
    pub fn theme(&self) -> &Theme {
        &self.theme
    }

-    /// ### theme_mut
-    ///
    /// Returns a mutable reference to the theme
    pub fn theme_mut(&mut self) -> &mut Theme {
        &mut self.theme
@@ -108,8 +98,6 @@ impl ThemeProvider {

    // -- io

-    /// ### load
-    ///
    /// Load theme from file
    pub fn load(&mut self) -> Result<(), SerializerError> {
        if self.degraded {
@@ -146,8 +134,6 @@ impl ThemeProvider {
        }
    }

-    /// ### save
-    ///
    /// Save theme to file
    pub fn save(&self) -> Result<(), SerializerError> {
        if self.degraded {
@@ -235,8 +221,6 @@ mod test {
        assert!(ThemeProvider::new(Path::new("/tmp/oifoif/omar")).is_err());
    }

-    /// ### get_theme_path
-    ///
    /// Get paths for theme file
    fn get_theme_path(dir: &Path) -> PathBuf {
        let mut p: PathBuf = PathBuf::from(dir);