Fix warnings in doc comments

Escape square brackets comments containing "[INFO]", "[WARNING]", "[ERROR]"

Suppress automatic link markup warning

src/error.rs

@@ -38,7 +38,7 @@ pub type Result<T> = std::result::Result<T, Error>;
 /// Pretty final error message for end users, crashing the program after display.
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct FinalError {
-    /// Should be made of just one line, appears after the "[ERROR]" part
+    /// Should be made of just one line, appears after the "\[ERROR\]" part
     title: String,
     /// Shown as a unnumbered list in yellow
     details: Vec<String>,

src/lib.rs

@@ -1,6 +1,10 @@
 //! This library is just meant to supply needs for the `ouch` binary crate.
 
 #![warn(missing_docs)]
+// Bare URLs in doc comments are not a problem since this project is primarily
+// used as a binary. Since `clap` doesn't remove URL markup in it's help output,
+// we don't mark them as URLs. This suppresses the relevant rustdoc warning:
+#![allow(rustdoc::bare_urls)]
 
 // Macros should be declared before
 pub mod macros;

src/macros.rs

@@ -1,6 +1,6 @@
 //! Macros used on ouch.
 
-/// Macro that prints [INFO] messages, wraps [`println`].
+/// Macro that prints \[INFO\] messages, wraps [`println`].
 #[macro_export]
 macro_rules! info {
     ($($arg:tt)*) => {
@@ -9,14 +9,14 @@ macro_rules! info {
     };
 }
 
-/// Helper to display "[INFO]", colored yellow
+/// Helper to display "\[INFO\]", colored yellow
 pub fn _info_helper() {
     use crate::utils::colors::{RESET, YELLOW};
 
     print!("{}[INFO]{} ", *YELLOW, *RESET);
 }
 
-/// Macro that prints [WARNING] messages, wraps [`println`].
+/// Macro that prints \[WARNING\] messages, wraps [`println`].
 #[macro_export]
 macro_rules! warning {
     ($($arg:tt)*) => {
@@ -25,7 +25,7 @@ macro_rules! warning {
     };
 }
 
-/// Helper to display "[INFO]", colored yellow
+/// Helper to display "\[WARNING\]", colored orange
 pub fn _warning_helper() {
     use crate::utils::colors::{ORANGE, RESET};
 

src/utils/formatting.rs

@@ -9,7 +9,7 @@ use std::{
 ///
 /// This is different from [`Path::display`].
 ///
-/// See https://gist.github.com/marcospb19/ebce5572be26397cf08bbd0fd3b65ac1 for a comparison.
+/// See <https://gist.github.com/marcospb19/ebce5572be26397cf08bbd0fd3b65ac1> for a comparison.
 pub fn to_utf(os_str: impl AsRef<OsStr>) -> String {
     let text = format!("{:?}", os_str.as_ref());
     text.trim_matches('"').to_string()

src/utils/fs.rs

@@ -59,7 +59,7 @@ pub fn cd_into_same_dir_as(filename: &Path) -> crate::Result<PathBuf> {
 }
 
 /// Try to detect the file extension by looking for known magic strings
-/// Source: https://en.wikipedia.org/wiki/List_of_file_signatures
+/// Source: <https://en.wikipedia.org/wiki/List_of_file_signatures>
 pub fn try_infer_extension(path: &Path) -> Option<Extension> {
     fn is_zip(buf: &[u8]) -> bool {
         buf.len() >= 3