diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml
index 8778a14..a32186b 100644
--- a/.idea/inspectionProfiles/Project_Default.xml
+++ b/.idea/inspectionProfiles/Project_Default.xml
@@ -3,6 +3,9 @@
+
+
+
diff --git a/Cargo.toml b/Cargo.toml
index a5491c0..9cf8b23 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -51,7 +51,7 @@ infer = { version = "0.5.0", optional = true }
[target.'cfg(not(all(target_endian = "big", target_pointer_width = "32")))'.dependencies]
# the seemingly weird target constraint here is due to this:
-# https://github.com/bodil/smartstring/blob/v0.2.7/src/config.rs#L102-L104
+# https://github.com/bodil/smartstring/blob/v0.2.9/src/config.rs#L91-L93
# essentially, smartstring is intentionally blocked from compiling on 32-bit big endian archs, so our dependency on it
# needs to be too. otherwise, fif won't work on platforms like powerpc, even though this dependency is the only
# blocker -- fif runs just fine on powerpc without smartstring. or at least, just fine under qemu user-mode powerpc ~u0
diff --git a/src/findings.rs b/src/findings.rs
index f20e44d..eea6279 100644
--- a/src/findings.rs
+++ b/src/findings.rs
@@ -1,8 +1,8 @@
// SPDX-FileCopyrightText: 2021 Lynnesbian
// SPDX-License-Identifier: LGPL-3.0-or-later
-//! The [`Findings`] and [`ScanError`] structs, used for conveying whether a given file was able to be scanned and
-//! whether its MIME type could be inferred.
+//! The [`Findings`] and [`ScanError`] structs, used for conveying whether a given file was able to be scanned, whether
+//! its MIME type could be inferred, and whether the file should be renamed.
use std::cmp::Ordering;
use std::fmt::{Display, Formatter};
@@ -15,7 +15,7 @@ use serde::{ser::SerializeStruct, Serializer};
use crate::files::mime_extension_lookup;
use crate::String;
-/// Information about a scanned file.
+/// Information about a successfully scanned file.
#[derive(Eq, PartialEq, Debug)]
pub struct Findings {
/// The location of the scanned file.
@@ -72,6 +72,7 @@ impl serde::Serialize for Findings {
}
}
+/// Errors that can occur while scanning a file with [`scan_file`](crate::files::scan_file).
#[derive(Debug, PartialEq, PartialOrd, Ord, Eq)]
#[cfg_attr(feature = "json", derive(serde::Serialize))]
#[cfg_attr(feature = "json", serde(tag = "type", content = "path"))]
diff --git a/src/formats.rs b/src/formats.rs
index 6ad0e60..a21403c 100644
--- a/src/formats.rs
+++ b/src/formats.rs
@@ -1,7 +1,9 @@
// SPDX-FileCopyrightText: 2021 Lynnesbian
// SPDX-License-Identifier: LGPL-3.0-or-later
-//! The various formats that [fif](crate) can output to.
+//! Logic for handling the various output formats that fif can output to.
+
+#![allow(missing_copy_implementations)]
use std::ffi::OsStr;
use std::io::{self, Write};
@@ -17,7 +19,7 @@ use crate::utils::CLAP_LONG_VERSION;
use crate::Findings;
use crate::String;
-/// A macro for creating an array of `Writable`s without needing to pepper your code with `into()`s.
+/// A macro for creating an array of [`Writable`]s without needing to pepper your code with `into()`s.
/// # Usage
/// ```
/// use crate::fif::writables;
@@ -46,7 +48,7 @@ macro_rules! writables {
}
#[macro_export]
-/// Does the same thing as [writables], but adds a Newline to the end.
+/// Does the same thing as [`writables`], but adds a Newline to the end.
macro_rules! writablesln {
[$($args:tt),+] => {
&[$(writables!(@do $args),)* writables!(@do Newline)]
diff --git a/src/lib.rs b/src/lib.rs
index 84c187e..cca3ecb 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,11 +1,15 @@
-#![forbid(unsafe_code)]
-
// SPDX-FileCopyrightText: 2021 Lynnesbian
// SPDX-License-Identifier: LGPL-3.0-or-later
//! This library consists of all of the things fif needs to run. It only exists as a library to separate code, and to
-//! make testing a bit easier. I don't recommend using this as a library for your crate, as it may have breaking
-//! changes without incrementing the major version, as it's really only meant to be a place for fif's internals to live.
+//! make documentation and testing a bit easier. I don't recommend using this as a library for your crate, as it may
+//! have breaking changes without incrementing the major version - it's really only meant to be a place for fif's
+//! internals to live.
+//!
+//! You can view [fif's README](https://gitlab.com/Lynnesbian/fif/-/blob/master/README.md#fif) to learn more.
+
+#![forbid(unsafe_code)]
+#![warn(trivial_casts, unused_lifetimes, unused_qualifications, missing_copy_implementations, unused_allocation)]
pub mod files;
pub mod findings;
@@ -22,20 +26,25 @@ use crate::mime_db::MimeDb;
cfg_if! {
if #[cfg(not(all(target_endian = "big", target_pointer_width = "32")))] {
- // most architectures
+ /// On most architectures, this is a type alias for [`SmartString`](crate). However, on [architectures
+ /// unsupported by `smartstring`](https://github.com/bodil/smartstring/blob/v0.2.9/src/config.rs#L91-L93), this
+ /// is simply an alias to [`std::string::String`].
pub use smartstring::alias::String;
} else {
- // powerpc and other big endian 32-bit archs
+ /// On most architectures, this is a type alias for [`SmartString`](crate). However, on [architectures
+ /// unsupported by `smartstring`](https://github.com/bodil/smartstring/blob/v0.2.9/src/config.rs#L91-L93), this
+ /// is simply an alias to [`std::string::String`].
+ // one particular arch that this needs to be turned off for is powerpc (the 32 bit variant that the pre-G5
+ // powerpc macs used)
pub use std::string::String;
}
}
-
cfg_if! {
if #[cfg(any(all(unix, feature = "infer-backend"), all(not(unix), not(feature = "xdg-mime-backend"))))] {
- /// A [`Lazy`] holding an instance of [`mime_db::MimeDb`].
+ /// A [`Lazy`] holding an instance of [`mime_db::MimeDb`]. Initialised at program startup.
pub static MIMEDB: Lazy = Lazy::new(crate::mime_db::InferDb::init);
} else {
- /// A [`Lazy`] holding an instance of [`mime_db::MimeDb`].
+ /// A [`Lazy`] holding an instance of [`mime_db::MimeDb`]. Initialised at program startup.
pub static MIMEDB: Lazy = Lazy::new(crate::mime_db::XdgDb::init);
}
}
diff --git a/src/main.rs b/src/main.rs
index f4a1b61..09959d6 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -4,7 +4,7 @@
// fif - a command-line tool for detecting and optionally correcting files with incorrect extensions.
#![forbid(unsafe_code)]
-#![warn(trivial_casts, unused_lifetimes, unused_qualifications)]
+#![warn(trivial_casts, unused_lifetimes, unused_qualifications, missing_copy_implementations, unused_allocation)]
use std::io::{stdin, stdout, BufWriter, Write};
use std::process::exit;
diff --git a/src/mime_db.rs b/src/mime_db.rs
index 875533e..0a81a7e 100644
--- a/src/mime_db.rs
+++ b/src/mime_db.rs
@@ -1,11 +1,20 @@
// SPDX-FileCopyrightText: 2021 Lynnesbian
// SPDX-License-Identifier: LGPL-3.0-or-later
-//! Backend-neutral Mime database implementation.
+//! Backend-neutral Mime database abstraction.
use cfg_if::cfg_if;
use mime::Mime;
+/// A thin wrapper around either [`Infer`] or [`xdg-mime::SharedMimeInfo`], depending on which [cargo features]
+/// fif was compiled with. By default, fif uses an [`Infer`]-based implementation on Windows, and an
+/// [`xdg-mime`]-based one everywhere else. This behaviour can be changed at compile time by using the aforementioned
+/// [cargo features].
+///
+/// [cargo features]: https://gitlab.com/Lynnesbian/fif/-/wikis/Cargo-Features
+/// [`Infer`]: https://docs.rs/infer/
+/// [`xdg-mime::SharedMimeInfo`]: https://docs.rs/xdg-mime/0/xdg_mime/struct.SharedMimeInfo.html
+/// [`xdg-mime`]: https://docs.rs/xdg-mime/
pub trait MimeDb {
/// Initialise the database.
fn init() -> Self;
@@ -17,6 +26,7 @@ cfg_if! {
if #[cfg(any(all(unix, feature = "infer-backend"), all(not(unix), not(feature = "xdg-mime-backend"))))] {
use std::str::FromStr;
+ /// The [`Infer`](https://docs.rs/infer/)-based implementation of [`MimeDb`].
pub struct InferDb {
db: infer::Infer,
}
@@ -93,10 +103,11 @@ cfg_if! {
}
fn get_type(&self, data: &[u8]) -> Option {
- self.db.get(data).map(|f| Mime::from_str(f.mime_type()).unwrap())
+ self.db.get(data).map(|f| Mime::from_str(f.mime_type())).ok()
}
}
} else {
+ /// The [`xdg-mime`](https://docs.rs/xdg-mime/)-based implementation of [`MimeDb`].
pub struct XdgDb {
db: xdg_mime::SharedMimeInfo,
}
diff --git a/src/parameters.rs b/src/parameters.rs
index 95133d9..68a3b9d 100644
--- a/src/parameters.rs
+++ b/src/parameters.rs
@@ -1,7 +1,7 @@
// SPDX-FileCopyrightText: 2021 Lynnesbian
// SPDX-License-Identifier: LGPL-3.0-or-later
-//! [Clap] struct used to parse command line arguments.
+//! Command line argument parsing logic and associated functions.
use std::collections::BTreeSet;
use std::path::PathBuf;
@@ -14,13 +14,17 @@ use crate::String as StringType;
cfg_if! {
if #[cfg(windows)] {
+ /// The default [`OutputFormat`] to use.
const DEFAULT_FORMAT: &str = "powershell";
} else {
+ /// The default [`OutputFormat`] to use.
const DEFAULT_FORMAT: &str = "sh";
}
}
-#[derive(Clap, PartialEq, Debug)]
+#[derive(Clap, PartialEq, Debug, Copy, Clone)]
+/// The format to use when running fif without the `--fix` flag. Specified at runtime with the `-o`/`--output-format`
+/// flag.
pub enum OutputFormat {
/// A Bourne shell compatible script.
#[clap(alias = "shell", alias = "bash")]
@@ -35,7 +39,9 @@ pub enum OutputFormat {
Json,
}
-#[derive(Clap, PartialEq, Debug)]
+#[derive(Clap, PartialEq, Debug, Copy, Clone)]
+/// Specifies under what conditions the user should be prompted when running fif in `--fix` mode. Defaults to `Error`.
+/// Specified at runtime with the `-p`/`--prompt` flag.
pub enum Prompt {
/// Never prompt.
Never,
@@ -60,6 +66,7 @@ pub enum Prompt {
setting(AppSettings::ColoredHelp),
max_term_width = 120
)]
+/// [`Clap`]-derived struct used to parse command line arguments.
pub struct Parameters {
/// Automatically rename files to use the correct extension, prompting the user for every rename.
#[clap(long)]
@@ -71,7 +78,7 @@ pub struct Parameters {
/// Requires --fix. Allow overwriting files. Warning: When used in combination with `--prompt never`, fif will
/// overwrite files without prompting!
- #[clap(short = 'n', long, requires = "fix")]
+ #[clap(long, requires = "fix")]
pub overwrite: bool,
// NOTE: clap's comma-separated argument parser makes it impossible to specify extensions with commas in their name -
@@ -170,6 +177,7 @@ pub struct Parameters {
pub jobs: usize,
}
+/// Validation function for argument parsing that ensures passed-in extensions are lowercase.
fn lowercase_exts(exts: &str) -> Result<(), String> {
// TODO: i would much rather accept uppercase exts and convert them to lowercase than just rejecting lowercase exts...
if exts.to_lowercase() != exts {
@@ -179,7 +187,7 @@ fn lowercase_exts(exts: &str) -> Result<(), String> {
}
/// Further options relating to scanning.
-#[derive(PartialEq, Debug)]
+#[derive(PartialEq, Debug, Copy, Clone)]
#[allow(clippy::struct_excessive_bools)]
pub struct ScanOpts {
/// Whether hidden files and directories should be scanned.
@@ -282,7 +290,7 @@ impl Parameters {
}
/// Sets of extensions for use with [Parameter](crate::parameters::Parameters)'s `-E` flag.
-#[derive(Clap, PartialEq, Debug)]
+#[derive(Clap, PartialEq, Debug, Copy, Clone)]
pub enum ExtensionSet {
/// Extensions used for image file formats, such as `png`, `jpeg`, `webp`, etc.
Images,
diff --git a/src/utils.rs b/src/utils.rs
index 189b78c..fc867e3 100644
--- a/src/utils.rs
+++ b/src/utils.rs
@@ -21,11 +21,11 @@ cfg_if! {
}
}
-/// The version defined in Cargo.toml, prefixed with a v (e.g. "v0.3.1")
+/// The version defined in Cargo.toml, prefixed with a v (e.g. "v0.4.0")
pub(crate) static CLAP_VERSION: Lazy = Lazy::new(|| String::from("v") + VERSION.unwrap_or("???"));
-/// Similar to [`CLAP_VERSION`], followed by the chosen backend and abbreviated git commit hash in parentheses - For
-/// example, "v0.3.6 (XDG-Mime backend, commit #043e097)"
+/// The version defined in Cargo.toml, prefixed with a v (e.g. "v0.4.0"), followed by the chosen backend and
+/// abbreviated git commit hash in parentheses - For example, "v0.4.0 (XDG-Mime backend, commit #043e097)"
pub static CLAP_LONG_VERSION: Lazy = Lazy::new(|| {
format!(
"v{} ({} backend, commit #{})",