From b5ef95b6efedfe962a25cd2e4a8f7f598c22426c Mon Sep 17 00:00:00 2001
From: Lynnesbian <lynne@bune.city>
Date: Wed, 6 Oct 2021 01:30:13 +1000
Subject: [PATCH] documentation

---
 .idea/inspectionProfiles/Project_Default.xml |  3 +++
 Cargo.toml                                   |  2 +-
 src/findings.rs                              |  7 ++---
 src/formats.rs                               |  8 +++---
 src/lib.rs                                   | 27 +++++++++++++-------
 src/main.rs                                  |  2 +-
 src/mime_db.rs                               | 15 +++++++++--
 src/parameters.rs                            | 20 ++++++++++-----
 src/utils.rs                                 |  6 ++---
 9 files changed, 62 insertions(+), 28 deletions(-)

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 @@
     <option name="myName" value="Project Default" />
     <inspection_tool class="DuplicatedCode" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
     <inspection_tool class="RegExpRepeatedSpace" enabled="true" level="INFORMATION" enabled_by_default="true" />
+    <inspection_tool class="RsExperimentalChecks" enabled="true" level="ERROR" enabled_by_default="true" />
+    <inspection_tool class="RsUnusedImport" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="RsVariableMutable" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
     <inspection_tool class="ShellCheck" enabled="true" level="ERROR" enabled_by_default="true">
       <shellcheck_settings value="SC2016" />
     </inspection_tool>
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<mime_db::InferDb> = 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<mime_db::XdgDb> = 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<Mime> {
-				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<String> = 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<String> = Lazy::new(|| {
 	format!(
 		"v{} ({} backend, commit #{})",