From c1a3a89fb19ae9adf6addf401ebb1a6cd8ad6f7d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Tue, 26 Jan 2021 13:21:55 +0100
Subject: [PATCH] Vk: doc++

---
 doc/developers.dox             |  6 +++---
 src/Magnum/Vk/DeviceFeatures.h | 33 ++++++++++++++++++++-------------
 2 files changed, 23 insertions(+), 16 deletions(-)

diff --git a/doc/developers.dox b/doc/developers.dox
index 572bf7a37..7e1985c64 100644
--- a/doc/developers.dox
+++ b/doc/developers.dox
@@ -865,10 +865,10 @@ pointers on a class that needs them:
 3.  Add a `@see` block, referencing related features if applicable,
     crossreference the newly added value from the values it refers to as well
 4.  Reference the extension / version it was added in via `@requires_vkXY`
-5.  Add the new members to `Magnum/Vk/Implementation/deviceFeatureMapping.hpp`
-    to the correct place with a `_cver()` or `_cext()` macro as appropriate
-6.  If APIs depending on this feature are already exposed, reference the
+5.  If APIs depending on this feature are already exposed, reference the
     feature from those
+6.  Add the new members to `Magnum/Vk/Implementation/deviceFeatureMapping.hpp`
+    to the correct place with a `_cver()` or `_cext()` macro as appropriate
 7.  Extend `Magnum/Vk/Implementation/DeviceFeatures.h` with the new feature
     struct, added to relatively the same place as in the enum header
 8.  Extend @ref Vk::DeviceProperties::features():
diff --git a/src/Magnum/Vk/DeviceFeatures.h b/src/Magnum/Vk/DeviceFeatures.h
index 4fe443858..33f138a70 100644
--- a/src/Magnum/Vk/DeviceFeatures.h
+++ b/src/Magnum/Vk/DeviceFeatures.h
@@ -42,9 +42,9 @@ namespace Magnum { namespace Vk {
 @brief Device feature
 @m_since_latest
 
-Contains information stored in the @type_vk{PhysicalDeviceFeatures2} structure
-chain. Values correspond to equivalently named structure fields, usually just
-with the first letter uppercase instead of lowercase.
+Contains information stored in the @type_vk_keyword{PhysicalDeviceFeatures2}
+structure chain. Values correspond to equivalently named structure fields,
+usually just with the first letter uppercase instead of lowercase.
 @see @ref DeviceFeatures, @ref DeviceProperties::features(),
     @ref Device::enabledFeatures()
 
@@ -243,8 +243,17 @@ enum class DeviceFeature: UnsignedShort {
     ShaderImageGatherExtended,
 
     /**
-     * Whether *all* shader storage image extended formats are supported.
-     * @todoc link to the formats once we have our own PixelFormat enum
+     * Whether @ref PixelFormat::R8Unorm, @ref PixelFormat::RG8Unorm,
+     * @ref PixelFormat::R8Snorm, @ref PixelFormat::RG8Snorm,
+     * @ref PixelFormat::R8UI, @ref PixelFormat::RG8UI, @ref PixelFormat::R8I,
+     * @ref PixelFormat::RG8I, @ref PixelFormat::R16Unorm,
+     * @ref PixelFormat::RG16Unorm, @ref PixelFormat::RGBA16Unorm,
+     * @ref PixelFormat::R16Snorm, @ref PixelFormat::RG16Snorm,
+     * @ref PixelFormat::RGBA16Snorm, @ref PixelFormat::R16UI,
+     * @ref PixelFormat::RG16UI, @ref PixelFormat::R16I,
+     * @ref PixelFormat::RG16I, @ref PixelFormat::R16F,
+     * @ref PixelFormat::RG16F are *all* supported for shader storage.
+     * @todoc link to the 10/10/10/2 and 10.11.10F formats once exposed
      */
     ShaderStorageImageExtendedFormats,
 
@@ -584,9 +593,8 @@ enum class DeviceFeature: UnsignedShort {
     /* VkPhysicalDeviceImagelessFramebufferFeatures, #109 */
 
     /**
-     * Specifying image view for attachments is possible at render pass begin
-     * time.
-     * @todoc crosslink with RenderPass::begin() when that's implemented.
+     * Specifying image view for attachments is possible at a time
+     * @ref CommandBuffer::beginRenderPass() is called.
      * @requires_vk12 Extension @vk_extension{KHR,imageless_framebuffer}
      */
     ImagelessFramebuffer,
@@ -1195,7 +1203,7 @@ enum class DeviceFeature: UnsignedShort {
      * depth/stencil layouts can be used.
      * @requires_vk12 Extension @vk_extension{KHR,separate_depth_stencil_layouts}
      * @todoc link to the actual ImageAspect and ImageLayout members once they
-     *      exist
+     *      all exist
      */
     SeparateDepthStencilLayouts,
 
@@ -1229,11 +1237,10 @@ enum class DeviceFeature: UnsignedShort {
     BufferDeviceAddressCaptureReplay,
 
     /**
-     * Whether @ref DeviceFeature::BufferDeviceAddress for logical devices
-     * created with multiple physical devices is supported.
+     * Whether @ref DeviceFeature::BufferDeviceAddress,
+     * @ref DeviceFeature::RayTracingPipeline and @ref DeviceFeature::RayQuery
+     * for logical devices created with multiple physical devices is supported.
      * @requires_vk12 Extension @vk_extension{KHR,buffer_device_address}
-     * @todoc this also references `rayTracingPipeline`, `rayQuery`, update
-     *      when those are exposed
      */
     BufferDeviceAddressMultiDevice,