generator: Mark hyperlinks as such

"cargo doc" reports (in a CI build): warning: this URL is not a hyperlink --> x11rb-protocol/src/protocol/damage.rs:444:9 | 444 | /// See https://www.x.org/releases/current/doc/damageproto/damageproto.txt | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<https://www.x.org/releases/current/doc/damageproto/damageproto.txt>` | = note: bare URLs are not automatically turned into clickable links = note: `#[warn(rustdoc::bare_urls)]` on by default The URL in question comes from the XML and is not marked as anything. Thus, this commit adds the regex crate as a dependency to the code generator and uses a regex to find and mark URLs. The regex used for URLs is quite basic, but seems to work for now. Signed-off-by: Uli Schlachter <[email protected]>
psychon · Oct 6, 2023 · 7b7d40d · 7b7d40d
1 parent aca14e3
commit 7b7d40d
Show file tree

Hide file tree

Showing 5 changed files with 23 additions and 11 deletions.
diff --git a/generator/Cargo.toml b/generator/Cargo.toml
@@ -9,3 +9,4 @@ publish = false
 [dependencies]
 roxmltree = "0.18.0"
 xcbgen = { path = "../xcbgen-rs" }
+regex = "1.9"
diff --git a/generator/src/generator/namespace/mod.rs b/generator/src/generator/namespace/mod.rs
@@ -1,9 +1,13 @@
 #![allow(clippy::cognitive_complexity, clippy::too_many_arguments)]
 
+use std::borrow::Cow;
 use std::cell::RefCell;
 use std::collections::{HashMap, HashSet};
 use std::fmt::Write;
 use std::rc::Rc;
+use std::sync::OnceLock;
+
+use regex::Regex;
 
 use xcbgen::defs as xcbdefs;
 
@@ -1092,7 +1096,7 @@ impl<'ns, 'c> NamespaceGenerator<'ns, 'c> {
                 if line.trim().is_empty() {
                     outln!(out, "///");
                 } else {
-                    outln!(out, "/// {}", line.trim());
+                    outln!(out, "/// {}", add_doc_markup(line.trim()));
                 }
             }
         }
@@ -1595,3 +1599,10 @@ impl<'ns, 'c> NamespaceGenerator<'ns, 'c> {
         }
     }
 }
+
+fn add_doc_markup(line: &str) -> Cow<'_, str> {
+    // The regex finds URLs and is used to marks them as hyperlinks for rustdoc
+    static REGEX: OnceLock<Regex> = OnceLock::new();
+    let regex = REGEX.get_or_init(|| Regex::new("https?://[a-zA-Z0-9-_/\\.]+").unwrap());
+    regex.replace_all(line, "<$0>")
+}
diff --git a/x11rb-async/src/protocol/damage.rs b/x11rb-async/src/protocol/damage.rs
@@ -131,7 +131,7 @@ where
 /// Remove regions from a previously created Damage object..
 ///
 /// This updates the regions of damage recorded in a a Damage object.
-/// See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
+/// See <https://www.x.org/releases/current/doc/damageproto/damageproto.txt>
 /// for details.
 ///
 /// # Fields
@@ -158,7 +158,7 @@ where
 /// Add a region to a previously created Damage object..
 ///
 /// This updates the regions of damage recorded in a a Damage object.
-/// See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
+/// See <https://www.x.org/releases/current/doc/damageproto/damageproto.txt>
 /// for details.
 ///
 /// # Fields
@@ -245,7 +245,7 @@ pub trait ConnectionExt: RequestConnection {
     /// Remove regions from a previously created Damage object..
     ///
     /// This updates the regions of damage recorded in a a Damage object.
-    /// See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
+    /// See <https://www.x.org/releases/current/doc/damageproto/damageproto.txt>
     /// for details.
     ///
     /// # Fields
@@ -261,7 +261,7 @@ pub trait ConnectionExt: RequestConnection {
     /// Add a region to a previously created Damage object..
     ///
     /// This updates the regions of damage recorded in a a Damage object.
-    /// See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
+    /// See <https://www.x.org/releases/current/doc/damageproto/damageproto.txt>
     /// for details.
     ///
     /// # Fields

diff --git a/x11rb-protocol/src/protocol/damage.rs b/x11rb-protocol/src/protocol/damage.rs
@@ -441,7 +441,7 @@ pub const SUBTRACT_REQUEST: u8 = 3;
 /// Remove regions from a previously created Damage object..
 ///
 /// This updates the regions of damage recorded in a a Damage object.
-/// See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
+/// See <https://www.x.org/releases/current/doc/damageproto/damageproto.txt>
 /// for details.
 ///
 /// # Fields
@@ -519,7 +519,7 @@ pub const ADD_REQUEST: u8 = 4;
 /// Add a region to a previously created Damage object..
 ///
 /// This updates the regions of damage recorded in a a Damage object.
-/// See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
+/// See <https://www.x.org/releases/current/doc/damageproto/damageproto.txt>
 /// for details.
 ///
 /// # Fields

diff --git a/x11rb/src/protocol/damage.rs b/x11rb/src/protocol/damage.rs
@@ -132,7 +132,7 @@ where
 /// Remove regions from a previously created Damage object..
 ///
 /// This updates the regions of damage recorded in a a Damage object.
-/// See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
+/// See <https://www.x.org/releases/current/doc/damageproto/damageproto.txt>
 /// for details.
 ///
 /// # Fields
@@ -160,7 +160,7 @@ where
 /// Add a region to a previously created Damage object..
 ///
 /// This updates the regions of damage recorded in a a Damage object.
-/// See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
+/// See <https://www.x.org/releases/current/doc/damageproto/damageproto.txt>
 /// for details.
 ///
 /// # Fields
@@ -248,7 +248,7 @@ pub trait ConnectionExt: RequestConnection {
     /// Remove regions from a previously created Damage object..
     ///
     /// This updates the regions of damage recorded in a a Damage object.
-    /// See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
+    /// See <https://www.x.org/releases/current/doc/damageproto/damageproto.txt>
     /// for details.
     ///
     /// # Fields
@@ -264,7 +264,7 @@ pub trait ConnectionExt: RequestConnection {
     /// Add a region to a previously created Damage object..
     ///
     /// This updates the regions of damage recorded in a a Damage object.
-    /// See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
+    /// See <https://www.x.org/releases/current/doc/damageproto/damageproto.txt>
     /// for details.
     ///
     /// # Fields