Vk: rethink "creation" docs.

Although the APIs don't look like that right now, in many cases creation
of a particular Vulkan object isn't all that's there for it. So change
the section names from a generic "Usage" to "Creation".

doc/snippets/MagnumVk.cpp

@@ -121,17 +121,17 @@ Vk::Device device{instance, std::move(info)};
 
 {
 Vk::Device device{NoCreate};
-/* [Buffer-usage] */
+/* [Buffer-creation] */
 Vk::Buffer buffer{device,
     Vk::BufferCreateInfo{Vk::BufferUsage::VertexBuffer, 1024*1024},
     Vk::MemoryFlag::DeviceLocal
 };
-/* [Buffer-usage] */
+/* [Buffer-creation] */
 }
 
 {
 Vk::Device device{NoCreate};
-/* [Buffer-usage-custom-allocation] */
+/* [Buffer-creation-custom-allocation] */
 Vk::Buffer buffer{device,
     Vk::BufferCreateInfo{Vk::BufferUsage::VertexBuffer, 1024*1024},
     NoAllocate
@@ -145,40 +145,40 @@ Vk::Memory memory{device, Vk::MemoryAllocateInfo{
 }};
 
 buffer.bindMemory(memory, 0);
-/* [Buffer-usage-custom-allocation] */
+/* [Buffer-creation-custom-allocation] */
 }
 
 {
-/* [CommandPool-usage] */
+/* [CommandPool-creation] */
 Vk::Device device{DOXYGEN_IGNORE(NoCreate)};
 
 Vk::CommandPool graphicsCommandPool{device, Vk::CommandPoolCreateInfo{
     device.properties().pickQueueFamily(Vk::QueueFlag::Graphics)
 }};
-/* [CommandPool-usage] */
+/* [CommandPool-creation] */
 
-/* [CommandPool-usage-allocate] */
+/* [CommandPool-allocation] */
 Vk::CommandBuffer commandBuffer = graphicsCommandPool.allocate();
 
 // fill the buffer, submit …
-/* [CommandPool-usage-allocate] */
+/* [CommandPool-allocation] */
 }
 
 {
 Vk::Instance instance;
-/* [Device-usage-construct-queue] */
+/* [Device-creation-construct-queue] */
 Vk::Queue queue{NoCreate};
 Vk::Device device{instance, Vk::DeviceCreateInfo{Vk::pickDevice(instance)}
     .addQueues(Vk::QueueFlag::Graphics, {0.0f}, {queue})
 };
-/* [Device-usage-construct-queue] */
+/* [Device-creation-construct-queue] */
 }
 
 {
 Vk::Instance instance;
 Vk::DeviceProperties properties{NoCreate};
 using namespace Containers::Literals;
-/* [Device-usage-extensions] */
+/* [Device-creation-extensions] */
 Vk::Device device{instance, Vk::DeviceCreateInfo{DOXYGEN_IGNORE(properties)}
     DOXYGEN_IGNORE()
     .addEnabledExtensions<                         // predefined extensions
@@ -186,13 +186,13 @@ Vk::Device device{instance, Vk::DeviceCreateInfo{DOXYGEN_IGNORE(properties)}
         Vk::Extensions::KHR::device_group>()
     .addEnabledExtensions({"VK_NV_mesh_shader"_s}) // can be plain strings too
 };
-/* [Device-usage-extensions] */
+/* [Device-creation-extensions] */
 }
 
 {
 Vk::Instance instance;
 using namespace Containers::Literals;
-/* [Device-usage-check-supported] */
+/* [Device-creation-check-supported] */
 Vk::DeviceProperties properties = Vk::pickDevice(instance);
 Vk::ExtensionProperties extensions = properties.enumerateExtensionProperties();
 
@@ -202,7 +202,7 @@ if(extensions.isSupported<Vk::Extensions::EXT::index_type_uint8>())
 if(extensions.isSupported("VK_NV_mesh_shader"_s))
     info.addEnabledExtensions({"VK_NV_mesh_shader"_s});
 DOXYGEN_IGNORE()
-/* [Device-usage-check-supported] */
+/* [Device-creation-check-supported] */
 }
 
 {
@@ -246,17 +246,17 @@ if(device.isExtensionEnabled<Vk::Extensions::EXT::index_type_uint8>()) {
 
 {
 Vk::Device device{NoCreate};
-/* [Image-usage] */
+/* [Image-creation] */
 Vk::Image image{device, Vk::ImageCreateInfo2D{
         Vk::ImageUsage::Sampled, VK_FORMAT_R8G8B8A8_SRGB, {1024, 1024}, 1
     }, Vk::MemoryFlag::DeviceLocal
 };
-/* [Image-usage] */
+/* [Image-creation] */
 }
 
 {
 Vk::Device device{NoCreate};
-/* [Image-usage-custom-allocation] */
+/* [Image-creation-custom-allocation] */
 Vk::Image image{device, Vk::ImageCreateInfo2D{
         Vk::ImageUsage::Sampled, VK_FORMAT_R8G8B8A8_SRGB, {1024, 1024}, 1
     }, NoAllocate
@@ -270,34 +270,34 @@ Vk::Memory memory{device, Vk::MemoryAllocateInfo{
 }};
 
 image.bindMemory(memory, 0);
-/* [Image-usage-custom-allocation] */
+/* [Image-creation-custom-allocation] */
 }
 
 {
 int argc{};
 const char** argv{};
-/* [Instance-usage-minimal] */
+/* [Instance-creation-minimal] */
 Vk::Instance instance{{argc, argv}};
-/* [Instance-usage-minimal] */
+/* [Instance-creation-minimal] */
 }
 
 {
 int argc{};
 const char** argv{};
-/* [Instance-usage] */
+/* [Instance-creation] */
 using namespace Containers::Literals;
 
 Vk::Instance instance{Vk::InstanceCreateInfo{argc, argv}
     .setApplicationInfo("My Vulkan Application"_s, Vk::version(1, 2, 3))
 };
-/* [Instance-usage] */
+/* [Instance-creation] */
 }
 
 {
 int argc{};
 const char** argv{};
 using namespace Containers::Literals;
-/* [Instance-usage-layers-extensions] */
+/* [Instance-creation-layers-extensions] */
 Vk::Instance instance{Vk::InstanceCreateInfo{argc, argv}
     DOXYGEN_IGNORE()
     .addEnabledLayers({"VK_LAYER_KHRONOS_validation"_s})
@@ -306,14 +306,14 @@ Vk::Instance instance{Vk::InstanceCreateInfo{argc, argv}
         Vk::Extensions::KHR::external_fence_capabilities>()
     .addEnabledExtensions({"VK_KHR_xcb_surface"_s}) // can be plain strings too
 };
-/* [Instance-usage-layers-extensions] */
+/* [Instance-creation-layers-extensions] */
 }
 
 {
 int argc{};
 const char** argv{};
 using namespace Containers::Literals;
-/* [Instance-usage-check-supported] */
+/* [Instance-creation-check-supported] */
 /* Query layer and extension support */
 Vk::LayerProperties layers = Vk::enumerateLayerProperties();
 Vk::InstanceExtensionProperties extensions =
@@ -329,7 +329,7 @@ if(extensions.isSupported<Vk::Extensions::EXT::debug_report>())
 DOXYGEN_IGNORE()
 
 Vk::Instance instance{info};
-/* [Instance-usage-check-supported] */
+/* [Instance-creation-check-supported] */
 }
 
 {
@@ -375,7 +375,7 @@ if(instance.isExtensionEnabled<Vk::Extensions::EXT::debug_utils>()) {
 {
 Vk::Device device{NoCreate};
 Containers::ArrayView<const char> vertexData, indexData;
-/* [Memory-usage] */
+/* [Memory-allocation] */
 /* Create buffers without allocating them */
 Vk::Buffer vertices{device,
     Vk::BufferCreateInfo{Vk::BufferUsage::VertexBuffer, vertexData.size()},
@@ -404,7 +404,7 @@ const UnsignedLong indicesOffset = verticesRequirements.alignedSize(alignment);
 /* Bind the respective sub-ranges to the buffers */
 vertices.bindMemory(memory, 0);
 indices.bindMemory(memory, indicesOffset);
-/* [Memory-usage] */
+/* [Memory-allocation] */
 
 /* [Memory-mapping] */
 /* The memory gets unmapped again at the end of scope */
@@ -419,7 +419,7 @@ indices.bindMemory(memory, indicesOffset);
 
 {
 Vk::Device device{DOXYGEN_IGNORE(NoCreate)};
-/* [RenderPass-usage] */
+/* [RenderPass-creation] */
 Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
     .setAttachments({
         VK_FORMAT_R8G8B8A8_SRGB,
@@ -430,12 +430,12 @@ Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
         .setDepthStencilAttachment(1)
     )
 };
-/* [RenderPass-usage] */
+/* [RenderPass-creation] */
 }
 
 {
 Vk::Device device{DOXYGEN_IGNORE(NoCreate)};
-/* [RenderPass-usage-load-store] */
+/* [RenderPass-creation-load-store] */
 Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
     .setAttachments({
         {VK_FORMAT_R8G8B8A8_SRGB, Vk::AttachmentLoadOperation::Clear, {}},
@@ -443,12 +443,12 @@ Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
     })
     DOXYGEN_IGNORE()
 };
-/* [RenderPass-usage-load-store] */
+/* [RenderPass-creation-load-store] */
 }
 
 {
 Vk::Device device{DOXYGEN_IGNORE(NoCreate)};
-/* [RenderPass-usage-layout] */
+/* [RenderPass-creation-layout] */
 Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
     .setAttachments({
         {VK_FORMAT_R8G8B8A8_SRGB,
@@ -465,12 +465,12 @@ Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
         .setDepthStencilAttachment({1, Vk::ImageLayout::ColorAttachment})
     )
 };
-/* [RenderPass-usage-layout] */
+/* [RenderPass-creation-layout] */
 }
 
 {
 Vk::Device device{DOXYGEN_IGNORE(NoCreate)};
-/* [Shader-usage] */
+/* [Shader-creation] */
 Vk::ShaderCreateInfo info{
     CORRADE_INTERNAL_ASSERT_EXPRESSION(Utility::Directory::read("shader.spv"))
 };
@@ -478,7 +478,7 @@ Vk::ShaderCreateInfo info{
 DOXYGEN_IGNORE()
 
 Vk::Shader shader{device, info};
-/* [Shader-usage] */
+/* [Shader-creation] */
 }
 
 {

src/Magnum/Vk/Buffer.h

@@ -97,8 +97,8 @@ CORRADE_ENUMSET_OPERATORS(BufferUsages)
 @brief Buffer creation info
 @m_since_latest
 
-Wraps a @type_vk_keyword{BufferCreateInfo}. See @ref Buffer for usage
-information.
+Wraps a @type_vk_keyword{BufferCreateInfo}. See
+@ref Vk-Buffer-creation "Buffer creation" for usage information.
 */
 class MAGNUM_VK_EXPORT BufferCreateInfo {
     public:
@@ -178,25 +178,25 @@ CORRADE_ENUMSET_OPERATORS(BufferCreateInfo::Flags)
 
 Wraps a @type_vk_keyword{Buffer} and its memory.
 
-@section Vk-Buffer-usage Basic usage
+@section Vk-Buffer-creation Buffer creation
 
 Pass a @ref BufferCreateInfo with desired usage and size to the @ref Buffer
 constructor together with specifying @ref MemoryFlags for the allocation.
 
-@snippet MagnumVk.cpp Buffer-usage
+@snippet MagnumVk.cpp Buffer-creation
 
 @attention At this point, a dedicated allocation is used, subsequently
     accessible through @ref dedicatedMemory(). This behavior may change in the
     future.
 
-@section Vk-Buffer-usage-custom-allocation Custom memory allocation
+@subsection Vk-Buffer-creation-custom-allocation Custom memory allocation
 
 Using @ref Buffer(Device&, const BufferCreateInfo&, NoAllocateT), the buffer
 will be created without any memory bound. Buffer memory requirements can be
 then queried using @ref memoryRequirements() and an allocated memory bound with
 @ref bindMemory(). See @ref Memory for further details about memory allocation.
 
-@snippet MagnumVk.cpp Buffer-usage-custom-allocation
+@snippet MagnumVk.cpp Buffer-creation-custom-allocation
 
 Using @ref bindDedicatedMemory() instead of @ref bindMemory() will transfer
 ownership of the @ref Memory to the buffer instance, making it subsequently

src/Magnum/Vk/CommandPool.h

@@ -44,8 +44,8 @@ namespace Magnum { namespace Vk {
 @brief Command pool creation info
 @m_since_latest
 
-Wraps a @type_vk_keyword{CommandPoolCreateInfo}. See @ref CommandPool for usage
-information.
+Wraps a @type_vk_keyword{CommandPoolCreateInfo}. See
+@ref Vk-CommandPool-creation "Command pool creation" for usage information.
 */
 class MAGNUM_VK_EXPORT CommandPoolCreateInfo {
     public:
@@ -180,20 +180,20 @@ CORRADE_ENUMSET_OPERATORS(CommandPoolResetFlags)
 Wraps a @type_vk_keyword{CommandPool} and handles allocation of
 @ref CommandBuffer "CommandBuffer"s.
 
-@section Vk-CommandPool-usage Usage
+@section Vk-CommandPool-creation Command pool creation and buffer allocation
 
 A @ref CommandPoolCreateInfo doesn't need many inputs --- the only required is
 queue family index coming from @ref DeviceProperties of the device it's created
 on:
 
-@snippet MagnumVk.cpp CommandPool-usage
+@snippet MagnumVk.cpp CommandPool-creation
 
 After that, you can allocate command buffers as follows. The command buffers
 are freed at the end of their instance lifetime, you can also put all allocated
 buffers back to initial state by calling @ref reset(), or alternatively reset
 each buffer separately using @ref CommandBuffer::reset().
 
-@snippet MagnumVk.cpp CommandPool-usage-allocate
+@snippet MagnumVk.cpp CommandPool-allocation
 */
 class MAGNUM_VK_EXPORT CommandPool {
     public:

src/Magnum/Vk/Device.h

@@ -53,8 +53,8 @@ namespace Implementation {
 @brief Device creation info
 @m_since_latest
 
-Wraps a @type_vk_keyword{DeviceCreateInfo}. See @ref Device for usage
-information.
+Wraps a @type_vk_keyword{DeviceCreateInfo}. See
+@ref Vk-Device-creation "Device creation" for usage information.
 */
 class MAGNUM_VK_EXPORT DeviceCreateInfo {
     public:
@@ -294,7 +294,7 @@ CORRADE_ENUMSET_OPERATORS(DeviceCreateInfo::Flags)
 Wraps a @type_vk_keyword{Device} and stores device-specific Vulkan function
 pointers.
 
-@section Vk-Device-usage Usage
+@section Vk-Device-creation Device creation
 
 With an @ref Instance ready, a device has to be picked first. Commonly it's
 done by calling @ref pickDevice() and letting the library choose. This
@@ -311,7 +311,7 @@ That's done by creating an empty @ref Queue instance and then referencing it
 from @ref DeviceCreateInfo::addQueues(). After the device is constructed, the
 queue gets populated and is ready to be used.
 
-@snippet MagnumVk.cpp Device-usage-construct-queue
+@snippet MagnumVk.cpp Device-creation-construct-queue
 
 In the above snippet, we requested a graphics queue via a convenience API. The
 information about available queues and other device properties is stored in a
@@ -326,12 +326,12 @@ both string names as well as predefined *device* extensions from the
 @ref Extensions namespace. Later on, presence of predefined extensions can be
 checked with @ref isExtensionEnabled().
 
-@snippet MagnumVk.cpp Device-usage-extensions
+@snippet MagnumVk.cpp Device-creation-extensions
 
 Usually you'll be first checking for extension availability instead, which is
 again accessible through the @ref DeviceProperties instance:
 
-@snippet MagnumVk.cpp Device-usage-check-supported
+@snippet MagnumVk.cpp Device-creation-check-supported
 
 With both @ref Instance and @ref Device created, you can proceed to setting up
 a @ref CommandPool.

src/Magnum/Vk/DeviceProperties.h

@@ -253,8 +253,8 @@ of @type_vk_keyword{PhysicalDeviceProperties},
 @type_vk_keyword{PhysicalDeviceQueueFamilyProperties} and
 @type_vk_keyword{PhysicalDeviceMemoryProperties}.
 
-See the @ref Vk-Device-usage "Device class docs" for an example of using this
-class for enumerating available devices and picking one of them.
+See the @ref Vk-Device-creation "Device creation docs" for an example of using
+this class for enumerating available devices and picking one of them.
 
 @see @ref pickDevice(), @ref enumerateDevices()
 */

src/Magnum/Vk/ExtensionProperties.h

@@ -48,9 +48,9 @@ namespace Magnum { namespace Vk {
 Provides a searchable container of Vulkan device extensions enumerated with
 @ref DeviceProperties::enumerateExtensionProperties().
 
-See the @ref Vk-Device-usage "Device class docs" for an example of using this
-class for checking available extensions before enabling them on a device. See
-@ref Vk-Instance-usage "Instance class docs" for the same but using
+See the @ref Vk-Device-creation "Device creation docs" for an example of using
+this class for checking available extensions before enabling them on a device.
+See @ref Vk-Instance-creation "Instance creation docs" for the same but using
 @ref InstanceExtensionProperties.
 
 @see @type_vk_keyword{ExtensionProperties}

src/Magnum/Vk/Image.h

@@ -225,8 +225,8 @@ enum class ImageLayout: Int {
 @brief Image creation info
 @m_since_latest
 
-Wraps a @type_vk_keyword{ImageCreateInfo}. See @ref Image for usage
-information.
+Wraps a @type_vk_keyword{ImageCreateInfo}. See
+@ref Vk-Image-creation "Image creation" for usage information.
 @see @ref ImageCreateInfo1D, @ref ImageCreateInfo2D, @ref ImageCreateInfo3D,
     @ref ImageCreateInfo1DArray, @ref ImageCreateInfo2DArray,
     @ref ImageCreateInfoCubeMap, @ref ImageCreateInfoCubeMapArray
@@ -525,26 +525,26 @@ class ImageCreateInfoCubeMapArray: public ImageCreateInfo {
 
 Wraps a @type_vk_keyword{Image} and its memory.
 
-@section Vk-Image-usage Basic usage
+@section Vk-Image-creation Image creation
 
 Pass one of the @ref ImageCreateInfo subclasses depending on desired image type
 with desired usage, format, size and other propoerties to the @ref Image
 constructor together with specifying @ref MemoryFlags for memory allocation.
 
-@snippet MagnumVk.cpp Image-usage
+@snippet MagnumVk.cpp Image-creation
 
 @attention At this point, a dedicated allocation is used, subsequently
     accessible through @ref dedicatedMemory(). This behavior may change in the
     future.
 
-@section Vk-Image-usage-custom-allocation Custom memory allocation
+@subsection Vk-Image-creation-custom-allocation Custom memory allocation
 
 Using @ref Image(Device&, const ImageCreateInfo&, NoAllocateT), the image will
 be created without any memory attached. Image memory requirements can be
 subsequently queried using @ref memoryRequirements() and an allocated memory
 bound with @ref bindMemory(). See @ref Memory for further details about memory allocation.
 
-@snippet MagnumVk.cpp Image-usage-custom-allocation
+@snippet MagnumVk.cpp Image-creation-custom-allocation
 
 Using @ref bindDedicatedMemory() instead of @ref bindMemory() will transfer
 ownership of the @ref Memory to the image instance, making it subsequently

src/Magnum/Vk/Instance.h

@@ -52,7 +52,8 @@ namespace Implementation {
 @m_since_latest
 
 Wraps a @type_vk_keyword{InstanceCreateInfo} and
-@type_vk_keyword{ApplicationInfo}. See @ref Instance for usage information.
+@type_vk_keyword{ApplicationInfo}. See
+@ref Vk-Instance-creation "Instance creation" for usage information.
 */
 class MAGNUM_VK_EXPORT InstanceCreateInfo {
     public:
@@ -244,19 +245,19 @@ CORRADE_ENUMSET_OPERATORS(InstanceCreateInfo::Flags)
 Wraps a @type_vk_keyword{Instance} and stores instance-specific Vulkan function
 pointers.
 
-@section Vk-Instance-usage Usage
+@section Vk-Instance-creation Instance creation
 
 While an @ref Instance can be default-constructed without much fuss, it's
 recommended to pass a @ref InstanceCreateInfo with at least the `argc` / `argv`
 pair, which allows you to use various `--magnum-*`
 @ref Vk-Instance-command-line "command-line options":
 
-@snippet MagnumVk.cpp Instance-usage-minimal
+@snippet MagnumVk.cpp Instance-creation-minimal
 
 In addition to command-line arguments, setting application info isn't strictly
 required either, but may be beneficial for the driver:
 
-@snippet MagnumVk.cpp Instance-usage
+@snippet MagnumVk.cpp Instance-creation
 
 <b></b>
 
@@ -277,14 +278,14 @@ both string names as well as predefined *instance* extensions from the
 @ref Extensions namespace. Later on, presence of predefined extensions can be
 checked with @ref isExtensionEnabled().
 
-@snippet MagnumVk.cpp Instance-usage-layers-extensions
+@snippet MagnumVk.cpp Instance-creation-layers-extensions
 
 However, with the above approach, if any layer or extension isn't available,
 the instance creation will abort. The recommended workflow is thus first
 checking layer and extension availability using @ref enumerateLayerProperties()
 and @ref enumerateInstanceExtensionProperties():
 
-@snippet MagnumVk.cpp Instance-usage-check-supported
+@snippet MagnumVk.cpp Instance-creation-check-supported
 
 Next step after creating a Vulkan instance is picking and creating a
 @ref Device.

src/Magnum/Vk/LayerProperties.h

@@ -51,8 +51,9 @@ and the assumption is that no drivers currently use rely on these anymore. See
 [§ 37.3.1](https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/chap38.html#extendingvulkan-layers-devicelayerdeprecation)
 for more information.
 
-See the @ref Vk-Instance-usage "Instance class docs" for an example of using
-this class for checking available layers before enabling them on an instance.
+See the @ref Vk-Instance-creation "Instance creation docs" for an example of
+using this class for checking available layers before enabling them on an
+instance.
 
 @see @ref ExtensionProperties, @ref enumerateInstanceExtensionProperties(),
     @type_vk_keyword{LayerProperties}

src/Magnum/Vk/Memory.h

@@ -201,8 +201,8 @@ class MAGNUM_VK_EXPORT MemoryRequirements {
 @brief Memory allocation info
 @m_since_latest
 
-Wraps a @type_vk_keyword{MemoryAllocateInfo}. See @ref Memory for usage
-information.
+Wraps a @type_vk_keyword{MemoryAllocateInfo}. See
+@ref Vk-Memory-allocation "Memory allocation" for usage information.
 */
 class MAGNUM_VK_EXPORT MemoryAllocateInfo {
     public:
@@ -262,7 +262,7 @@ class MAGNUM_VK_EXPORT MemoryAllocateInfo {
 
 Wraps a @type_vk_keyword{DeviceMemory} and handles its allocation and mapping.
 
-@section Vk-Memory-usage Usage
+@section Vk-Memory-allocation Memory allocation
 
 By default, the memory will get allocated for you during the creation of
 @ref Buffer, @ref Image and other objects. In case you want to handle the
@@ -283,7 +283,7 @@ tag to constructors of these objects), it consists of these steps:
 The following example allocates a single block memory for two buffers, one
 containing vertex and the other index data:
 
-@snippet MagnumVk.cpp Memory-usage
+@snippet MagnumVk.cpp Memory-allocation
 
 @section Vk-Memory-mapping Memory mapping
 

src/Magnum/Vk/RenderPass.h

@@ -800,8 +800,8 @@ class MAGNUM_VK_EXPORT SubpassDependency {
 @m_since_latest
 
 Wraps a @type_vk_keyword{RenderPassCreateInfo2} /
-@type_vk_keyword{RenderPassCreateInfo}. See @ref RenderPass for usage
-information.
+@type_vk_keyword{RenderPassCreateInfo}. See
+@ref Vk-RenderPass-creation "Render pass creation" for usage information.
 
 @section Vk-RenderPassCreateInfo-compatibility Compatibility with VkRenderPassCreateInfo
 
@@ -1011,12 +1011,12 @@ descriptions, subpasses and their dependencies. The render pass description is
 independent of any specific image views used for attachments, these two are
 connected together in a framebuffer.
 
-@section Vk-RenderPass-usage Basic usage
+@section Vk-RenderPass-creation Render pass creation
 
-A render pass is a set of attachments, described by @ref AttachmentDescription
-instances, subpasses operating on those attachments, described by a
-@ref SubpassDescription using @ref AttachmentReference instances, and subpass
-dependencies, described by @ref SubpassDependency.
+@ref RenderPassCreateInfo is a set of attachments, described by
+@ref AttachmentDescription instances, subpasses operating on those attachments,
+described by a @ref SubpassDescription using @ref AttachmentReference
+instances, and subpass dependencies, described by @ref SubpassDependency.
 
 A render pass has to have at least one subpass. It's common to have just one
 subpass but while the subpass isn't required to operate on any attachments,
@@ -1028,7 +1028,7 @@ on a color and a combined depth/stencil attachment. The main parameter an
 @ref RenderPassCreateInfo::setAttachments() array, and it's actually
 @ref AttachmentReference instances:
 
-@snippet MagnumVk.cpp RenderPass-usage
+@snippet MagnumVk.cpp RenderPass-creation
 
 The above again does a conservative estimate that you'd want to preserve the
 attachment contents between render passes. Usually you'd want to clear the
@@ -1039,7 +1039,7 @@ passing appropriate @ref AttachmentLoadOperation /
 conveniently the zero values, which means you can use @cpp {} @ce instead of
 typing them out in full:
 
-@snippet MagnumVk.cpp RenderPass-usage-load-store
+@snippet MagnumVk.cpp RenderPass-creation-load-store
 
 Vulkan makes heavy use of image layouts for optimal memory access
 and in all the cases above, @ref ImageLayout::General is used as an implicit
@@ -1051,7 +1051,7 @@ more optimal by explicitly specifying both a concrete initial and final layout
 in the @ref AttachmentDescription constructors and in
 each @link AttachmentReference @endlink:
 
-@snippet MagnumVk.cpp RenderPass-usage-layout
+@snippet MagnumVk.cpp RenderPass-creation-layout
 */
 class MAGNUM_VK_EXPORT RenderPass {
     public:

src/Magnum/Vk/Shader.h

@@ -44,8 +44,8 @@ namespace Magnum { namespace Vk {
 @brief Shader creation info
 @m_since_latest
 
-Wraps a @type_vk_keyword{ShaderModuleCreateInfo}. See @ref Shader for usage
-information.
+Wraps a @type_vk_keyword{ShaderModuleCreateInfo}. See
+@ref Vk-Shader-creation "Shader creation" for usage information.
 */
 class MAGNUM_VK_EXPORT ShaderCreateInfo {
     public:
@@ -173,7 +173,7 @@ CORRADE_ENUMSET_OPERATORS(ShaderCreateInfo::Flags)
 
 Wraps a @type_vk_keyword{ShaderModule}.
 
-@section Vk-Shader-usage Usage
+@section Vk-Shader-creation Shader creation
 
 The @ref ShaderCreateInfo structure takes a single required parameter, which is
 the SPIR-V binary. Besides accepting a @ref Corrade::Containers::ArrayView<const void>,
@@ -182,7 +182,7 @@ to which any container is convertible, it can also take ownership of a
 keeping a loaded file in scope until it's consumed by the @ref Shader
 constructor:
 
-@snippet MagnumVk.cpp Shader-usage
+@snippet MagnumVk.cpp Shader-creation
 */
 class MAGNUM_VK_EXPORT Shader {
     public: