From 6d4369fcbc93abddcbb1927750dafa55e0f8b2f9 Mon Sep 17 00:00:00 2001 From: Marijn Suijten Date: Tue, 5 May 2026 12:21:56 +0200 Subject: [PATCH] Generate deprecation docs for types like we do for commands When handling the new `` element where new ``s and ``s can deprecate earlier functionality with an explanation link, these links were only forwarded to commands but not types (only defines). Forward it so that it's also readable for the user. --- ash/src/vk/definitions.rs | 52 +++++++--------------------- generator/src/lib.rs | 71 ++++++++++++++++++++++++++++++++------- 2 files changed, 71 insertions(+), 52 deletions(-) diff --git a/ash/src/vk/definitions.rs b/ash/src/vk/definitions.rs index d627db5c1..2027a7381 100644 --- a/ash/src/vk/definitions.rs +++ b/ash/src/vk/definitions.rs @@ -126,6 +126,8 @@ vk_bitflags_wrapped!(DeviceCreateFlags, Flags); #[repr(transparent)] #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] #[doc = ""] +#[doc = ""] +#[doc = "Deprecated: "] pub struct DescriptorPoolResetFlags(pub(crate) Flags); vk_bitflags_wrapped!(DescriptorPoolResetFlags, Flags); #[repr(transparent)] @@ -368,11 +370,7 @@ handle_nondispatchable!( BUFFER, doc = "" ); -handle_nondispatchable!( - BufferView, - BUFFER_VIEW, - doc = "" -); +handle_nondispatchable ! (BufferView , BUFFER_VIEW , doc = "\n\nDeprecated: ") ; handle_nondispatchable!( Image, IMAGE, @@ -393,31 +391,11 @@ handle_nondispatchable!( PIPELINE, doc = "" ); -handle_nondispatchable!( - PipelineLayout, - PIPELINE_LAYOUT, - doc = "" -); -handle_nondispatchable!( - Sampler, - SAMPLER, - doc = "" -); -handle_nondispatchable!( - DescriptorSet, - DESCRIPTOR_SET, - doc = "" -); -handle_nondispatchable!( - DescriptorSetLayout, - DESCRIPTOR_SET_LAYOUT, - doc = "" -); -handle_nondispatchable!( - DescriptorPool, - DESCRIPTOR_POOL, - doc = "" -); +handle_nondispatchable ! (PipelineLayout , PIPELINE_LAYOUT , doc = "\n\nDeprecated: ") ; +handle_nondispatchable ! (Sampler , SAMPLER , doc = "\n\nDeprecated: ") ; +handle_nondispatchable ! (DescriptorSet , DESCRIPTOR_SET , doc = "\n\nDeprecated: ") ; +handle_nondispatchable ! (DescriptorSetLayout , DESCRIPTOR_SET_LAYOUT , doc = "\n\nDeprecated: ") ; +handle_nondispatchable ! (DescriptorPool , DESCRIPTOR_POOL , doc = "\n\nDeprecated: ") ; handle_nondispatchable!( Fence, FENCE, @@ -438,16 +416,8 @@ handle_nondispatchable!( QUERY_POOL, doc = "" ); -handle_nondispatchable!( - Framebuffer, - FRAMEBUFFER, - doc = "" -); -handle_nondispatchable!( - RenderPass, - RENDER_PASS, - doc = "" -); +handle_nondispatchable ! (Framebuffer , FRAMEBUFFER , doc = "\n\nDeprecated: ") ; +handle_nondispatchable ! (RenderPass , RENDER_PASS , doc = "\n\nDeprecated: ") ; handle_nondispatchable!( PipelineCache, PIPELINE_CACHE, @@ -51823,6 +51793,8 @@ impl<'a> DescriptorBufferBindingPushDescriptorBufferHandleEXT<'a> { #[repr(C)] #[derive(Copy, Clone)] #[doc = ""] +#[doc = ""] +#[doc = "Deprecated: "] pub union DescriptorDataEXT<'a> { pub p_sampler: *const Sampler, pub p_combined_image_sampler: *const DescriptorImageInfo, diff --git a/generator/src/lib.rs b/generator/src/lib.rs index cfe17d0bd..8da9679f2 100644 --- a/generator/src/lib.rs +++ b/generator/src/lib.rs @@ -287,10 +287,8 @@ fn parse_c_parameter(i: &str) -> IResult<&str, CParameter<'_>> { .parse(i) } -fn khronos_link(name: &S) -> Literal { - Literal::string(&format!( - "" - )) +fn khronos_link(name: &S) -> String { + format!("") } fn deprecated_link(explanationlink: &S) -> String { @@ -1557,6 +1555,7 @@ pub fn generate_define( pub fn generate_typedef( typedef: &vkxml::Typedef, provided_by: &ProvidedBy<'_>, + deprecated_by: Option<&str>, ) -> Option { if typedef.basetype.is_empty() { // Ignore forward declarations @@ -1568,15 +1567,21 @@ pub fn generate_typedef( let provisional = provided_by .provisional .then(|| quote!(#[cfg(feature = "provisional")])); + let deprecated = deprecated_by.map(deprecated_link).map(|d| { + let d = format!("Deprecated: {d}"); + quote!(#[doc = ""] #[doc = #d]) + }); Some(quote! { #provisional #[doc = #khronos_link] + #deprecated pub type #typedef_name = #typedef_ty; }) } pub fn generate_bitmask( bitmask: &vkxml::Bitmask, provided_by: &ProvidedBy<'_>, + deprecated_by: Option<&str>, bitflags_cache: &mut HashSet, const_values: &mut BTreeMap, ) -> Option { @@ -1600,11 +1605,16 @@ pub fn generate_bitmask( let provisional = provided_by .provisional .then(|| quote!(#[cfg(feature = "provisional")])); + let deprecated = deprecated_by.map(deprecated_link).map(|d| { + let d = format!("Deprecated: {d}"); + quote!(#[doc = ""] #[doc = #d]) + }); Some(quote! { #provisional #[repr(transparent)] #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] #[doc = #khronos_link] + #deprecated pub struct #ident(pub(crate) #type_); vk_bitflags_wrapped!(#ident, #type_); }) @@ -2446,6 +2456,7 @@ struct PreprocessedMember<'a> { pub fn generate_struct( struct_: &vkxml::Struct, provided_by: &ProvidedBy<'_>, + deprecated_by: Option<&str>, allowed_types: &HashMap<&str, ProvidedBy<'_>>, vk_parse_types: &HashMap, union_types: &HashSet<&str>, @@ -2461,6 +2472,10 @@ pub fn generate_struct( let provisional = provided_by .provisional .then(|| quote!(#[cfg(feature = "provisional")])); + let deprecated = deprecated_by.map(deprecated_link).map(|d| { + let d = format!("Deprecated: {d}"); + quote!(#[doc = ""] #[doc = #d]) + }); if &struct_.name == "VkTransformMatrixKHR" { return quote! { @@ -2469,6 +2484,7 @@ pub fn generate_struct( #[cfg_attr(feature = "debug", derive(Debug))] #[derive(Copy, Clone, Default)] #[doc = #khronos_link] + #deprecated #[must_use] pub struct TransformMatrixKHR { pub matrix: [f32; 12], @@ -2725,29 +2741,34 @@ pub fn generate_struct( pub fn generate_handle( handle: &vkxml::Handle, provided_by: &ProvidedBy<'_>, + deprecated_by: Option<&str>, ) -> Option { if handle.name.is_empty() { return None; } - let khronos_link = khronos_link(&handle.name); + let mut doc = khronos_link(&handle.name); let name = handle.name.strip_prefix("Vk").unwrap(); let ty = format_ident!("{}", name.to_shouty_snake_case()); let name = format_ident!("{}", name); let provisional = provided_by .provisional .then(|| quote!(, cfg(feature = "provisional"))); + if let Some(d) = deprecated_by { + doc += &format!("\n\nDeprecated: {}", deprecated_link(d)); + } Some(match handle.ty { vkxml::HandleType::Dispatch => { - quote!(define_handle!(#name, #ty, doc = #khronos_link #provisional);) + quote!(define_handle!(#name, #ty, doc = #doc #provisional);) } vkxml::HandleType::NoDispatch => { - quote!(handle_nondispatchable!(#name, #ty, doc = #khronos_link #provisional);) + quote!(handle_nondispatchable!(#name, #ty, doc = #doc #provisional);) } }) } fn generate_funcptr( fnptr: &vkxml::FunctionPointer, provided_by: &ProvidedBy<'_>, + deprecated_by: Option<&str>, has_lifetimes: &HashSet, ) -> Option { let name = format_ident!("{}", fnptr.name); @@ -2771,10 +2792,15 @@ fn generate_funcptr( let provisional = provided_by .provisional .then(|| quote!(#[cfg(feature = "provisional")])); + let deprecated = deprecated_by.map(deprecated_link).map(|d| { + let d = format!("Deprecated: {d}"); + quote!(#[doc = ""] #[doc = #d]) + }); Some(quote! { #provisional #[allow(non_camel_case_types)] #[doc = #khronos_link] + #deprecated pub type #name = Option; }) } @@ -2782,6 +2808,7 @@ fn generate_funcptr( fn generate_union( union: &vkxml::Union, provided_by: &ProvidedBy<'_>, + deprecated_by: Option<&str>, has_lifetimes: &HashSet, ) -> Option { let name = name_to_tokens(&union.name); @@ -2799,12 +2826,17 @@ fn generate_union( let provisional = provided_by .provisional .then(|| quote!(#[cfg(feature = "provisional")])); + let deprecated = deprecated_by.map(deprecated_link).map(|d| { + let d = format!("Deprecated: {d}"); + quote!(#[doc = ""] #[doc = #d]) + }); let lifetime = has_lifetimes.contains(&name).then(|| quote!(<'a>)); Some(quote! { #provisional #[repr(C)] #[derive(Copy, Clone)] #[doc = #khronos_link] + #deprecated pub union #name #lifetime { #(#fields),* } @@ -2841,6 +2873,7 @@ pub fn generate_definition_vk_parse( pub fn generate_definition( definition: &vkxml::DefinitionsElement, allowed_types: &HashMap<&str, ProvidedBy<'_>>, + deprecated_types: &HashMap<&str, &str>, union_types: &HashSet<&str>, has_lifetimes: &HashSet, vk_parse_types: &HashMap, @@ -2850,14 +2883,17 @@ pub fn generate_definition( match *definition { vkxml::DefinitionsElement::Typedef(ref typedef) => { let provided_by = allowed_types.get(typedef.name.as_str())?; - generate_typedef(typedef, provided_by) + let deprecated_by = deprecated_types.get(typedef.name.as_str()).copied(); + generate_typedef(typedef, provided_by, deprecated_by) } vkxml::DefinitionsElement::Struct(ref struct_) => { let provided_by = allowed_types.get(struct_.name.as_str())?; + let deprecated_by = deprecated_types.get(struct_.name.as_str()).copied(); Some(generate_struct( struct_, provided_by, + deprecated_by, allowed_types, vk_parse_types, union_types, @@ -2866,19 +2902,29 @@ pub fn generate_definition( } vkxml::DefinitionsElement::Bitmask(ref mask) => { let provided_by = allowed_types.get(mask.name.as_str())?; - generate_bitmask(mask, provided_by, bitflags_cache, const_values) + let deprecated_by = deprecated_types.get(mask.name.as_str()).copied(); + generate_bitmask( + mask, + provided_by, + deprecated_by, + bitflags_cache, + const_values, + ) } vkxml::DefinitionsElement::Handle(ref handle) => { let provided_by = allowed_types.get(handle.name.as_str())?; - generate_handle(handle, provided_by) + let deprecated_by = deprecated_types.get(handle.name.as_str()).copied(); + generate_handle(handle, provided_by, deprecated_by) } vkxml::DefinitionsElement::FuncPtr(ref fp) => { let provided_by = allowed_types.get(fp.name.as_str())?; - generate_funcptr(fp, provided_by, has_lifetimes) + let deprecated_by = deprecated_types.get(fp.name.as_str()).copied(); + generate_funcptr(fp, provided_by, deprecated_by, has_lifetimes) } vkxml::DefinitionsElement::Union(ref union) => { let provided_by = allowed_types.get(union.name.as_str())?; - generate_union(union, provided_by, has_lifetimes) + let deprecated_by = deprecated_types.get(union.name.as_str()).copied(); + generate_union(union, provided_by, deprecated_by, has_lifetimes) } _ => None, } @@ -3563,6 +3609,7 @@ pub fn write_source_code>(vk_headers_dir: &Path, src_dir: P) { generate_definition( def, &required_types, + &deprecated_types, &union_types, &has_lifetimes, &vk_parse_types,