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

2021-11-23 20:11:42 +01:00 · 2021-11-23 20:11:42 +01:00 · 64f3de38ab
parent 9a35cff373
commit 64f3de38ab
4 changed files with 56 additions and 10 deletions
--- a/ash/src/vk/constants.rs
+++ b/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;
--- a/ash/src/vk/extensions.rs
+++ b/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'"]
--- a/ash/src/vk/feature_extensions.rs
+++ b/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'"]
--- a/generator/src/lib.rs
+++ b/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| {
-        constant.notation().map(|n| {
-            if n.to_lowercase().contains("backwards") {
-                quote!(#[deprecated = #n])
-            } else {
-                quote!(#[doc = #n])
-            }
-        })
-    });
+    let notations = constants.iter().map(|constant| constant.doc_attribute());

    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;
    }
 }