Replace <<ref>> in documentation with link to ref (#693)

Rustdoc since 1.66 points out that `<<ref>>` is malformed HTML, and the
resulting `<<devsandqueues-lost-device>>` isn't very helpful to users.
Convert it to the relevant link in both documentation and `Result`
`Display` to solve both issues at once.

ash/src/vk/enums.rs

@@ -966,7 +966,7 @@ impl Result {
     pub const ERROR_OUT_OF_DEVICE_MEMORY: Self = Self(-2);
     #[doc = "Initialization of an object has failed"]
     pub const ERROR_INITIALIZATION_FAILED: Self = Self(-3);
-    #[doc = "The logical device has been lost. See <<devsandqueues-lost-device>>"]
+    #[doc = "The logical device has been lost. See <https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#devsandqueues-lost-device>"]
     pub const ERROR_DEVICE_LOST: Self = Self(-4);
     #[doc = "Mapping of a memory object has failed"]
     pub const ERROR_MEMORY_MAP_FAILED: Self = Self(-5);
@@ -990,40 +990,7 @@ impl Result {
 impl ::std::error::Error for Result {}
 impl fmt::Display for Result {
     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
-        let name = match *self {
+        let name = match * self { Self :: SUCCESS => Some ("Command completed successfully") , Self :: NOT_READY => Some ("A fence or query has not yet completed") , Self :: TIMEOUT => Some ("A wait operation has not completed in the specified time") , Self :: EVENT_SET => Some ("An event is signaled") , Self :: EVENT_RESET => Some ("An event is unsignaled") , Self :: INCOMPLETE => Some ("A return array was too small for the result") , Self :: ERROR_OUT_OF_HOST_MEMORY => Some ("A host memory allocation has failed") , Self :: ERROR_OUT_OF_DEVICE_MEMORY => Some ("A device memory allocation has failed") , Self :: ERROR_INITIALIZATION_FAILED => Some ("Initialization of an object has failed") , Self :: ERROR_DEVICE_LOST => Some ("The logical device has been lost. See <https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#devsandqueues-lost-device>") , Self :: ERROR_MEMORY_MAP_FAILED => Some ("Mapping of a memory object has failed") , Self :: ERROR_LAYER_NOT_PRESENT => Some ("Layer specified does not exist") , Self :: ERROR_EXTENSION_NOT_PRESENT => Some ("Extension specified does not exist") , Self :: ERROR_FEATURE_NOT_PRESENT => Some ("Requested feature is not available on this device") , Self :: ERROR_INCOMPATIBLE_DRIVER => Some ("Unable to find a Vulkan driver") , Self :: ERROR_TOO_MANY_OBJECTS => Some ("Too many objects of the type have already been created") , Self :: ERROR_FORMAT_NOT_SUPPORTED => Some ("Requested format is not supported on this device") , Self :: ERROR_FRAGMENTED_POOL => Some ("A requested pool allocation has failed due to fragmentation of the pool's memory") , Self :: ERROR_UNKNOWN => Some ("An unknown error has occurred, due to an implementation or application bug") , _ => None , } ;
-            Self::SUCCESS => Some("Command completed successfully"),
-            Self::NOT_READY => Some("A fence or query has not yet completed"),
-            Self::TIMEOUT => Some("A wait operation has not completed in the specified time"),
-            Self::EVENT_SET => Some("An event is signaled"),
-            Self::EVENT_RESET => Some("An event is unsignaled"),
-            Self::INCOMPLETE => Some("A return array was too small for the result"),
-            Self::ERROR_OUT_OF_HOST_MEMORY => Some("A host memory allocation has failed"),
-            Self::ERROR_OUT_OF_DEVICE_MEMORY => Some("A device memory allocation has failed"),
-            Self::ERROR_INITIALIZATION_FAILED => Some("Initialization of an object has failed"),
-            Self::ERROR_DEVICE_LOST => {
-                Some("The logical device has been lost. See <<devsandqueues-lost-device>>")
-            }
-            Self::ERROR_MEMORY_MAP_FAILED => Some("Mapping of a memory object has failed"),
-            Self::ERROR_LAYER_NOT_PRESENT => Some("Layer specified does not exist"),
-            Self::ERROR_EXTENSION_NOT_PRESENT => Some("Extension specified does not exist"),
-            Self::ERROR_FEATURE_NOT_PRESENT => {
-                Some("Requested feature is not available on this device")
-            }
-            Self::ERROR_INCOMPATIBLE_DRIVER => Some("Unable to find a Vulkan driver"),
-            Self::ERROR_TOO_MANY_OBJECTS => {
-                Some("Too many objects of the type have already been created")
-            }
-            Self::ERROR_FORMAT_NOT_SUPPORTED => {
-                Some("Requested format is not supported on this device")
-            }
-            Self::ERROR_FRAGMENTED_POOL => Some(
-                "A requested pool allocation has failed due to fragmentation of the pool's memory",
-            ),
-            Self::ERROR_UNKNOWN => {
-                Some("An unknown error has occurred, due to an implementation or application bug")
-            }
-            _ => None,
-        };
         if let Some(x) = name {
             fmt.write_str(x)
         } else {

generator/src/lib.rs

@@ -19,6 +19,7 @@ use proc_macro2::{Delimiter, Group, Literal, Span, TokenStream, TokenTree};
 use quote::*;
 use regex::Regex;
 use std::{
+    borrow::Cow,
     collections::{BTreeMap, HashMap, HashSet},
     fmt::Display,
     path::Path,
@@ -196,6 +197,15 @@ pub trait ConstantExt {
     fn constant(&self, enum_name: &str) -> Constant;
     fn variant_ident(&self, enum_name: &str) -> Ident;
     fn notation(&self) -> Option<&str>;
+    fn formatted_notation(&self) -> Option<Cow<'_, str>> {
+        static DOC_LINK: Lazy<Regex> = Lazy::new(|| Regex::new(r#"<<([\w-]+)>>"#).unwrap());
+        self.notation().map(|n| {
+            DOC_LINK.replace(
+                n,
+                "<https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#${1}>",
+            )
+        })
+    }
     fn is_alias(&self) -> bool {
         false
     }
@@ -205,10 +215,8 @@ pub trait ConstantExt {
             Some(BACKWARDS_COMPATIBLE_ALIAS_COMMENT),
             "Backwards-compatible constants should not be emitted"
         );
-        match self.notation() {
+        match self.formatted_notation() {
-            Some(n) if n.starts_with("Alias") => {
+            Some(n) if n.starts_with("Alias") => quote!(#[deprecated = #n]),
-                quote!(#[deprecated = #n])
-            }
             Some(n) => quote!(#[doc = #n]),
             None => quote!(),
         }
@@ -1402,7 +1410,7 @@ pub fn generate_result(ident: Ident, enum_: &vk_parse::Enums) -> TokenStream {
         let (variant_name, notation) = match *elem {
             vk_parse::EnumsChild::Enum(ref constant) => (
                 constant.name.as_str(),
-                constant.comment.as_deref().unwrap_or(""),
+                constant.formatted_notation().unwrap_or(Cow::Borrowed("")),
             ),
             _ => {
                 return None;