generator: Add missing documentation to bitflag extension variants (#501)

ash/src/vk/constants.rs

@@ -5,6 +5,7 @@ pub const LUID_SIZE: usize = 8;
 pub const MAX_EXTENSION_NAME_SIZE: usize = 256;
 pub const MAX_DESCRIPTION_SIZE: usize = 256;
 pub const MAX_MEMORY_TYPES: usize = 32;
+#[doc = "The maximum number of unique memory heaps, each of which supporting 1 or more memory types"]
 pub const MAX_MEMORY_HEAPS: usize = 16;
 pub const LOD_CLAMP_NONE: f32 = 1000.00;
 pub const REMAINING_MIP_LEVELS: u32 = !0;

ash/src/vk/extensions.rs

@@ -660,10 +660,12 @@ impl StructureType {
 }
 #[doc = "Generated from 'VK_KHR_swapchain'"]
 impl SwapchainCreateFlagsKHR {
+    #[doc = "Allow images with VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT"]
     pub const SPLIT_INSTANCE_BIND_REGIONS: Self = Self(0b1);
 }
 #[doc = "Generated from 'VK_KHR_swapchain'"]
 impl SwapchainCreateFlagsKHR {
+    #[doc = "Swapchain is protected"]
     pub const PROTECTED: Self = Self(0b10);
 }
 impl KhrDisplayFn {
@@ -1971,6 +1973,7 @@ impl StructureType {
 }
 #[doc = "Generated from 'VK_EXT_debug_report'"]
 impl StructureType {
+    #[deprecated = "Backwards-compatible alias containing a typo"]
     pub const DEBUG_REPORT_CREATE_INFO_EXT: Self = Self::DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT;
 }
 #[doc = "Generated from 'VK_EXT_debug_report'"]
@@ -2052,10 +2055,12 @@ impl KhrSamplerMirrorClampToEdgeFn {
 }
 #[doc = "Generated from 'VK_KHR_sampler_mirror_clamp_to_edge'"]
 impl SamplerAddressMode {
+    #[doc = "Note that this defines what was previously a core enum, and so uses the 'value' attribute rather than 'offset', and does not have a suffix. This is a special case, and should not be repeated"]
     pub const MIRROR_CLAMP_TO_EDGE: Self = Self(4);
 }
 #[doc = "Generated from 'VK_KHR_sampler_mirror_clamp_to_edge'"]
 impl SamplerAddressMode {
+    #[deprecated = "Alias introduced for consistency with extension suffixing rules"]
     pub const MIRROR_CLAMP_TO_EDGE_KHR: Self = Self::MIRROR_CLAMP_TO_EDGE;
 }
 impl ImgFilterCubicFn {
@@ -2083,6 +2088,7 @@ impl Filter {
 }
 #[doc = "Generated from 'VK_IMG_filter_cubic'"]
 impl FormatFeatureFlags {
+    #[doc = "Format can be filtered with VK_FILTER_CUBIC_IMG when being sampled"]
     pub const SAMPLED_IMAGE_FILTER_CUBIC_IMG: Self = Self(0b10_0000_0000_0000);
 }
 impl AmdExtension17Fn {
@@ -2951,10 +2957,12 @@ impl StructureType {
 }
 #[doc = "Generated from 'VK_KHR_video_queue'"]
 impl ObjectType {
+    #[doc = "VkVideoSessionKHR"]
     pub const VIDEO_SESSION_KHR: Self = Self(1_000_023_000);
 }
 #[doc = "Generated from 'VK_KHR_video_queue'"]
 impl ObjectType {
+    #[doc = "VkVideoSessionParametersKHR"]
     pub const VIDEO_SESSION_PARAMETERS_KHR: Self = Self(1_000_023_001);
 }
 #[doc = "Generated from 'VK_KHR_video_queue'"]
@@ -4472,6 +4480,7 @@ impl PipelineCreateFlags {
 }
 #[doc = "Generated from 'VK_KHR_dynamic_rendering'"]
 impl PipelineCreateFlags {
+    #[deprecated = "Backwards-compatible alias containing a typo"]
     pub const RASTERIZATION_STATE_FRAGMENT_SHADING_RATE_ATTACHMENT_KHR: Self =
         Self::RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_KHR;
 }
@@ -4486,6 +4495,7 @@ impl PipelineCreateFlags {
 }
 #[doc = "Generated from 'VK_KHR_dynamic_rendering'"]
 impl PipelineCreateFlags {
+    #[deprecated = "Backwards-compatible alias containing a typo"]
     pub const RASTERIZATION_STATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_EXT: Self =
         Self::RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_EXT;
 }
@@ -6971,10 +6981,12 @@ impl StructureType {
 }
 #[doc = "Generated from 'VK_KHR_push_descriptor'"]
 impl DescriptorSetLayoutCreateFlags {
+    #[doc = "Descriptors are pushed via flink:vkCmdPushDescriptorSetKHR"]
     pub const PUSH_DESCRIPTOR_KHR: Self = Self(0b1);
 }
 #[doc = "Generated from 'VK_KHR_push_descriptor'"]
 impl DescriptorUpdateTemplateType {
+    #[doc = "Create descriptor update template for pushed descriptor updates"]
     pub const PUSH_DESCRIPTORS_KHR: Self = Self(1);
 }
 impl ExtConditionalRenderingFn {
@@ -7073,14 +7085,17 @@ impl StructureType {
 }
 #[doc = "Generated from 'VK_EXT_conditional_rendering'"]
 impl AccessFlags {
+    #[doc = "read access flag for reading conditional rendering predicate"]
     pub const CONDITIONAL_RENDERING_READ_EXT: Self = Self(0b1_0000_0000_0000_0000_0000);
 }
 #[doc = "Generated from 'VK_EXT_conditional_rendering'"]
 impl BufferUsageFlags {
+    #[doc = "Specifies the buffer can be used as predicate in conditional rendering"]
     pub const CONDITIONAL_RENDERING_EXT: Self = Self(0b10_0000_0000);
 }
 #[doc = "Generated from 'VK_EXT_conditional_rendering'"]
 impl PipelineStageFlags {
+    #[doc = "A pipeline stage for conditional rendering predicate fetch"]
     pub const CONDITIONAL_RENDERING_EXT: Self = Self(0b100_0000_0000_0000_0000);
 }
 impl KhrShaderFloat16Int8Fn {
@@ -7678,6 +7693,7 @@ impl StructureType {
 }
 #[doc = "Generated from 'VK_EXT_display_surface_counter'"]
 impl StructureType {
+    #[deprecated = "Backwards-compatible alias containing a typo"]
     pub const SURFACE_CAPABILITIES2_EXT: Self = Self::SURFACE_CAPABILITIES_2_EXT;
 }
 impl ExtDisplayControlFn {
@@ -8345,6 +8361,7 @@ impl ColorSpaceKHR {
 }
 #[doc = "Generated from 'VK_EXT_swapchain_colorspace'"]
 impl ColorSpaceKHR {
+    #[deprecated = "Backwards-compatible alias containing a typo"]
     pub const DCI_P3_LINEAR_EXT: Self = Self::DISPLAY_P3_LINEAR_EXT;
 }
 impl ExtHdrMetadataFn {
@@ -16882,6 +16899,7 @@ impl StructureType {
 }
 #[doc = "Generated from 'VK_INTEL_performance_query'"]
 impl StructureType {
+    #[deprecated = "Backwards-compatible alias containing a typo"]
     pub const QUERY_POOL_CREATE_INFO_INTEL: Self =
         Self::QUERY_POOL_PERFORMANCE_QUERY_CREATE_INFO_INTEL;
 }
@@ -22252,10 +22270,12 @@ impl AccessFlags2KHR {
 }
 #[doc = "Generated from 'VK_KHR_synchronization2'"]
 impl PipelineStageFlags2KHR {
+    #[doc = "A pipeline stage for conditional rendering predicate fetch"]
     pub const CONDITIONAL_RENDERING_EXT: Self = Self(0b100_0000_0000_0000_0000);
 }
 #[doc = "Generated from 'VK_KHR_synchronization2'"]
 impl AccessFlags2KHR {
+    #[doc = "read access flag for reading conditional rendering predicate"]
     pub const CONDITIONAL_RENDERING_READ_EXT: Self = Self(0b1_0000_0000_0000_0000_0000);
 }
 #[doc = "Generated from 'VK_KHR_synchronization2'"]
@@ -24417,6 +24437,7 @@ impl StructureType {
 }
 #[doc = "Generated from 'VK_FUCHSIA_buffer_collection'"]
 impl ObjectType {
+    #[doc = "VkBufferCollectionFUCHSIA"]
     pub const BUFFER_COLLECTION_FUCHSIA: Self = Self(1_000_366_000);
 }
 #[doc = "Generated from 'VK_FUCHSIA_buffer_collection'"]

ash/src/vk/feature_extensions.rs

@@ -58,6 +58,7 @@ impl PipelineCreateFlags {
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl DependencyFlags {
+    #[doc = "Dependency is across devices"]
     pub const DEVICE_GROUP: Self = Self(0b100);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
@@ -70,6 +71,7 @@ impl StructureType {
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl ImageCreateFlags {
+    #[doc = "Allows using VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions when binding memory to the image"]
     pub const SPLIT_INSTANCE_BIND_REGIONS: Self = Self(0b100_0000);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
@@ -82,6 +84,7 @@ impl StructureType {
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl MemoryHeapFlags {
+    #[doc = "If set, heap allocations allocate multiple instances by default"]
     pub const MULTI_INSTANCE: Self = Self(0b10);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
@@ -146,14 +149,17 @@ impl Result {
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl FormatFeatureFlags {
+    #[doc = "Format can be used as the source image of image transfer commands"]
     pub const TRANSFER_SRC: Self = Self(0b100_0000_0000_0000);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl FormatFeatureFlags {
+    #[doc = "Format can be used as the destination image of image transfer commands"]
     pub const TRANSFER_DST: Self = Self(0b1000_0000_0000_0000);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl ImageCreateFlags {
+    #[doc = "The 3D image can be viewed as a 2D or 2D array image"]
     pub const TYPE_2D_ARRAY_COMPATIBLE: Self = Self(0b10_0000);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
@@ -231,26 +237,32 @@ impl StructureType {
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl QueueFlags {
+    #[doc = "Queues may support protected operations"]
     pub const PROTECTED: Self = Self(0b1_0000);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl DeviceQueueCreateFlags {
+    #[doc = "Queue is a protected-capable device queue"]
     pub const PROTECTED: Self = Self(0b1);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl MemoryPropertyFlags {
+    #[doc = "Memory is protected"]
     pub const PROTECTED: Self = Self(0b10_0000);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl BufferCreateFlags {
+    #[doc = "Buffer requires protected memory"]
     pub const PROTECTED: Self = Self(0b1000);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl ImageCreateFlags {
+    #[doc = "Image requires protected memory"]
     pub const PROTECTED: Self = Self(0b1000_0000_0000);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl CommandPoolCreateFlags {
+    #[doc = "Command buffers allocated from pool are protected command buffers"]
     pub const PROTECTED: Self = Self(0b100);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
@@ -435,14 +447,17 @@ impl ImageCreateFlags {
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl FormatFeatureFlags {
+    #[doc = "Format can have midpoint rather than cosited chroma samples"]
     pub const MIDPOINT_CHROMA_SAMPLES: Self = Self(0b10_0000_0000_0000_0000);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl FormatFeatureFlags {
+    #[doc = "Format can be used with linear filtering whilst color conversion is enabled"]
     pub const SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER: Self = Self(0b100_0000_0000_0000_0000);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl FormatFeatureFlags {
+    #[doc = "Format can have different chroma, min and mag filters"]
     pub const SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER: Self =
         Self(0b1000_0000_0000_0000_0000);
 }
@@ -458,10 +473,12 @@ impl FormatFeatureFlags {
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl FormatFeatureFlags {
+    #[doc = "Format supports disjoint planes"]
     pub const DISJOINT: Self = Self(0b100_0000_0000_0000_0000_0000);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
 impl FormatFeatureFlags {
+    #[doc = "Format can have cosited rather than midpoint chroma samples"]
     pub const COSITED_CHROMA_SAMPLES: Self = Self(0b1000_0000_0000_0000_0000_0000);
 }
 #[doc = "Generated from 'VK_VERSION_1_1'"]
@@ -675,6 +692,7 @@ impl StructureType {
 }
 #[doc = "Generated from 'VK_VERSION_1_2'"]
 impl FormatFeatureFlags {
+    #[doc = "Format can be used with min/max reduction filtering"]
     pub const SAMPLED_IMAGE_FILTER_MINMAX: Self = Self(0b1_0000_0000_0000_0000);
 }
 #[doc = "Generated from 'VK_VERSION_1_2'"]

generator/src/lib.rs

@@ -359,6 +359,15 @@ pub trait ConstantExt {
     fn is_alias(&self) -> bool {
         false
     }
+    fn doc_attribute(&self) -> TokenStream {
+        match self.notation() {
+            Some(n) if n.starts_with("Backwards") || n.starts_with("Alias") => {
+                quote!(#[deprecated = #n])
+            }
+            Some(n) => quote!(#[doc = #n]),
+            None => quote!(),
+        }
+    }
 }
 
 impl ConstantExt for vkxml::ExtensionEnum {
@@ -1064,6 +1073,7 @@ fn generate_function_pointers<'a>(
 pub struct ExtensionConstant<'a> {
     pub name: &'a str,
     pub constant: Constant,
+    pub notation: Option<&'a str>,
 }
 impl<'a> ConstantExt for ExtensionConstant<'a> {
     fn constant(&self, _enum_name: &str) -> Constant {
@@ -1073,7 +1083,7 @@ impl<'a> ConstantExt for ExtensionConstant<'a> {
         variant_ident(enum_name, self.name)
     }
     fn notation(&self) -> Option<&str> {
-        None
+        self.notation
     }
 }
 
@@ -1103,6 +1113,7 @@ pub fn generate_extension_constants<'a>(
             let ext_constant = ExtensionConstant {
                 name: &enum_.name,
                 constant,
+                notation: enum_.comment.as_deref(),
             };
             let ident = name_to_tokens(&extends);
             const_values
@@ -1435,15 +1446,7 @@ pub fn bitflags_impl_block(
         })
         .collect_vec();
 
-    let notations = constants.iter().map(|constant| {
+    let notations = constants.iter().map(|constant| constant.doc_attribute());
-        constant.notation().map(|n| {
-            if n.to_lowercase().contains("backwards") {
-                quote!(#[deprecated = #n])
-            } else {
-                quote!(#[doc = #n])
-            }
-        })
-    });
 
     let variants =
         variants
@@ -2374,12 +2377,15 @@ pub fn generate_constant<'a>(
     let c = Constant::from_constant(constant);
     let name = constant_name(&constant.name);
     let ident = format_ident!("{}", name);
+    let notation = constant.doc_attribute();
+
     let ty = if name == "TRUE" || name == "FALSE" {
         CType::Bool32
     } else {
         c.ty()
     };
     quote! {
+        #notation
         pub const #ident: #ty = #c;
     }
 }