From c1add95e708a9d4ef101da25c25a832b6be22ac3 Mon Sep 17 00:00:00 2001
From: Anton Hermann <antonoehler@gmx.de>
Date: Sat, 13 Nov 2021 00:04:32 +0100
Subject: [PATCH] Fix warnings in doc comments

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

Suppress automatic link markup warning
---
 src/error.rs            | 2 +-
 src/lib.rs              | 4 ++++
 src/macros.rs           | 8 ++++----
 src/utils/formatting.rs | 2 +-
 src/utils/fs.rs         | 2 +-
 5 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/src/error.rs b/src/error.rs
index d9ac449..289efbc 100644
--- a/src/error.rs
+++ b/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>,
diff --git a/src/lib.rs b/src/lib.rs
index 9fa58cb..45013c2 100644
--- a/src/lib.rs
+++ b/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;
diff --git a/src/macros.rs b/src/macros.rs
index 349d7ea..49fd87c 100644
--- a/src/macros.rs
+++ b/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};
 
diff --git a/src/utils/formatting.rs b/src/utils/formatting.rs
index db2aef4..5a189db 100644
--- a/src/utils/formatting.rs
+++ b/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()
diff --git a/src/utils/fs.rs b/src/utils/fs.rs
index 034c3aa..f1d14ab 100644
--- a/src/utils/fs.rs
+++ b/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