Vk: document also what CreateInfo setters do to the underlying struct.

doc/developers.dox

@@ -792,6 +792,11 @@ unless it doesn't affect public API at all.
 -   The main constructor(s) should explicitly list what structure fields are
     filled to which value, and if the constructor isn't enough to get a working
     state, it should also clearly mention what needs to be done next
+-   For everything non-essential or what isn't practical to be set in
+    constructor a setter should be added. If applicable, document what
+    subsequent calls to the same function result in (for example when a list
+    gets cleared while all other functions append to lists). The docs should
+    again list what underlying structure fields are set to which value.
 -   Every class should have a @ref NoInitT constructor, which keeps the
     structure uninitialized and *doesn't* allocate any internal state
 -   Every class should have a constructor taking the underlying Vulkan

src/Magnum/Vk/DeviceCreateInfo.h

@@ -175,10 +175,18 @@ class MAGNUM_VK_EXPORT DeviceCreateInfo {
          * All listed extensions are expected to be supported either globally
          * or in at least one of the enabled layers, use
          * @ref ExtensionProperties::isSupported() to check for their presence.
-         *
          * The function makes copies of string views that are not global or
          * null-terminated, use the @link Containers::Literals::operator""_s() @endlink
          * literal to prevent that where possible.
+         *
+         * The following @type_vk{DeviceCreateInfo} fields are set by this
+         * function:
+         *
+         * -    `enabledExtensionCount` to the count of extensions added
+         *      previously by this function plus @cpp extensions.size() @ce
+         * -    `pEnabledExtensionNames` to an array containing all extension
+         *      strings added previously by this function together with ones
+         *      from @p extensions
          */
         DeviceCreateInfo& addEnabledExtensions(Containers::ArrayView<const Containers::StringView> extensions) &;
         /** @overload */
@@ -215,8 +223,13 @@ class MAGNUM_VK_EXPORT DeviceCreateInfo {
          * corresponding extension enabled via @ref addEnabledExtensions(). Use
          * @ref DeviceProperties::features() to check for feature support.
          *
-         * Depending on what features are enabled, a subset of the following
-         * structures will be added to the `pNext` chain:
+         * If Vulkan 1.1 is not supported and
+         * @vk_extension{KHR,get_physical_device_properties2} is not enabled on
+         * the instance, the `pEnabledFeatures` field in
+         * @type_vk{DeviceCreateInfo} is set to the Vulkan 1.0 subset of
+         * @p features. Otherwise, depending on what features are enabled, a
+         * subset of the following structures will be added to the `pNext`
+         * chain:
          *
          * -    @type_vk_keyword{PhysicalDeviceProtectedMemoryFeatures} (Vulkan
          *      1.1)
@@ -292,6 +305,16 @@ class MAGNUM_VK_EXPORT DeviceCreateInfo {
          * @return Reference to self (for method chaining)
          *
          * At least one queue has to be added.
+         *
+         * The following @type_vk{DeviceCreateInfo} fields are set by this
+         * function:
+         *
+         * -    `queueCreateInfoCount` to the count of queues added previously
+         *      by this function plus @cpp queues.size() @ce
+         * -    `pQueueCreateInfos` to an array containing all queue create
+         *      infos added previously by this function together with ones
+         *      from @p family and @p priorities
+         *
          * @see @ref DeviceProperties::pickQueueFamily()
          * @todoc link to addQueues(QueueFlags) once doxygen finally GROWS UP
          *      and can link to &-qualified functions FFS
@@ -331,8 +354,16 @@ class MAGNUM_VK_EXPORT DeviceCreateInfo {
          * @return Reference to self (for method chaining)
          *
          * Compared to @ref addQueues() this allows you to specify additional
-         * queue properties using the `pNext` chain. The info is uses as-is,
+         * queue properties using the `pNext` chain. The info is used as-is,
          * with all pointers expected to stay in scope until device creation.
+         *
+         * The following @type_vk{DeviceCreateInfo} fields are set by this
+         * function:
+         *
+         * -    `queueCreateInfoCount` to the count of queues added previously
+         *      by this function plus @cpp 1 @ce
+         * -    `pQueueCreateInfos` to an array containing all queue create
+         *      infos added previously by this function together with @p info
          */
         DeviceCreateInfo& addQueues(const VkDeviceQueueCreateInfo& info) &;
         /** @overload */

src/Magnum/Vk/InstanceCreateInfo.h

@@ -159,6 +159,13 @@ class MAGNUM_VK_EXPORT InstanceCreateInfo {
          * The function makes copies of string views that are not global or
          * null-terminated, use the @link Containers::Literals::operator""_s() @endlink
          * literal to prevent that where possible.
+         *
+         * The following @type_vk{InstanceCreateInfo} fields are set by this
+         * function:
+         *
+         * -    `pApplicationInfo`
+         * -    @cpp pApplicationInfo->pApplicationName @ce to @p name
+         * -    @cpp pApplicationInfo->applicationVersion @ce to @p version
          */
         InstanceCreateInfo& setApplicationInfo(Containers::StringView name, Version version);
 
@@ -175,6 +182,15 @@ class MAGNUM_VK_EXPORT InstanceCreateInfo {
          * The function makes copies of string views that are not global or
          * null-terminated, use the @link Containers::Literals::operator""_s() @endlink
          * literal to prevent that where possible.
+         *
+         * The following @type_vk{InstanceCreateInfo} fields are set by this
+         * function:
+         *
+         * -    `enabledLayerCount` to the count of layers added previously by
+         *      this function plus @cpp layers.size() @ce
+         * -    `pEnabledLayerNames` to an array containing all layer strings
+         *      added previously by this function together with ones from
+         *      @p layers
          */
         InstanceCreateInfo& addEnabledLayers(Containers::ArrayView<const Containers::StringView> layers);
         /** @overload */
@@ -195,6 +211,15 @@ class MAGNUM_VK_EXPORT InstanceCreateInfo {
          * The function makes copies of string views that are not global or
          * null-terminated, use the @link Containers::Literals::operator""_s() @endlink
          * literal to prevent that where possible.
+         *
+         * The following @type_vk{InstanceCreateInfo} fields are set by this
+         * function:
+         *
+         * -    `enabledExtensionCount` to the count of extensions added
+         *      previously by this function plus @cpp extensions.size() @ce
+         * -    `pEnabledExtensionNames` to an array containing all extension
+         *      strings added previously by this function together with ones
+         *      from @p extensions
          */
         InstanceCreateInfo& addEnabledExtensions(Containers::ArrayView<const Containers::StringView> extensions);
         /** @overload */

src/Magnum/Vk/RasterizationPipelineCreateInfo.h

@@ -454,8 +454,8 @@ class MAGNUM_VK_EXPORT RasterizationPipelineCreateInfo {
          * @f$ [0.0, 1.0] @f$.
          *
          * The following @type_vk{GraphicsPipelineCreateInfo} and substructure
-         * fields are modified, in addition to `sType` of newly referenced
-         * structures:
+         * fields are modified by this function, in addition to `sType` of
+         * newly referenced structures:
          *
          * -    `pViewportState`
          * -    @cpp pViewportState->viewportCount @ce to @cpp 1 @ce
@@ -501,8 +501,8 @@ class MAGNUM_VK_EXPORT RasterizationPipelineCreateInfo {
          * @brief Set dynamic states
          *
          * The following @type_vk{GraphicsPipelineCreateInfo} and substructure
-         * fields are modified, in addition to `sType` of newly referenced
-         * structures:
+         * fields are modified by this function, in addition to `sType` of
+         * newly referenced structures:
          *
          * -    `pDynamicState`
          * -    @cpp pDynamicState->dynamicStateCount @ce to count of values

src/Magnum/Vk/RenderPassCreateInfo.h

@@ -566,6 +566,12 @@ class MAGNUM_VK_EXPORT SubpassDescription {
          * either @ref ImageLayout::General or @ref ImageLayout::ShaderReadOnly;
          * use a default-constructed @ref AttachmentReference to specify that
          * given input will be unused.
+         *
+         * The following @type_vk{SubpassDescription2} fields are set by this
+         * function:
+         *
+         * -    `inputAttachmentCount` to @cpp attachments.size() @ce
+         * -    `pInputAttachments` to a copy of @p attachments
          */
         SubpassDescription& setInputAttachments(Containers::ArrayView<const AttachmentReference> attachments) &;
         /** @overload */
@@ -591,6 +597,14 @@ class MAGNUM_VK_EXPORT SubpassDescription {
          * @ref ImageLayout::ColorAttachment; use a default-constructed
          * @ref AttachmentReference to specify that given output will be
          * unused.
+         *
+         * The following @type_vk{SubpassDescription2} fields are set by this
+         * function:
+         *
+         * -    `colorAttachmentCount` to @cpp attachments.size() @ce
+         * -    `pColorAttachments` to a copy of @p attachments
+         * -    `pResolveAttachments` to a copy of @p resolveAttachments, if
+         *      the parameter is non-empty
          */
         #ifdef DOXYGEN_GENERATING_OUTPUT
         SubpassDescription& setColorAttachments(Containers::ArrayView<const AttachmentReference> attachments, Containers::ArrayView<const AttachmentReference> resolveAttachments = {}) &;
@@ -618,6 +632,11 @@ class MAGNUM_VK_EXPORT SubpassDescription {
          * with a default-constructed @ref AttachmentReference is equivalent to
          * not calling it at all, and both mean there's no depth/stencil
          * attachment.
+         *
+         * The following @type_vk{SubpassDescription2} fields are set by this
+         * function:
+         *
+         * -    `pDepthStencilAttachment` to a copy of @p attachment
          */
         SubpassDescription& setDepthStencilAttachment(AttachmentReference attachment) &;
         /** @overload */
@@ -631,6 +650,11 @@ class MAGNUM_VK_EXPORT SubpassDescription {
          * be preserved throughout the subpass. The @p attachment values are
          * indices into the list passed to
          * @ref RenderPassCreateInfo::setAttachments().
+         *
+         * The following @type_vk{SubpassDescription2} fields are set by this
+         * function:
+         *
+         * -    `pPreserveAttachments` to a copy of @p attachments
          */
         SubpassDescription& setPreserveAttachments(Containers::ArrayView<const UnsignedInt> attachments) &;
         /** @overload */
@@ -966,6 +990,12 @@ class MAGNUM_VK_EXPORT RenderPassCreateInfo {
          *
          * Subsequent calls to this function will *replace* the previous set,
          * not append to it.
+         *
+         * The following @type_vk{RenderPassCreateInfo2} fields are set by this
+         * function:
+         *
+         * -    `attachmentCount` to @cpp attachments.size() @ce
+         * -    `pAttachments` to a copy of @p attachments
          */
         RenderPassCreateInfo& setAttachments(Containers::ArrayView<const AttachmentDescription> attachments);
         /** @overload */
@@ -984,6 +1014,16 @@ class MAGNUM_VK_EXPORT RenderPassCreateInfo {
          *      to nested allocations inside @ref SubpassDescription, it's more
          *      efficient to *move* the instances one by one than having to
          *      deep-copy a list.
+         *
+         * The following @type_vk{RenderPassCreateInfo2} fields are set by this
+         * function:
+         *
+         * -    `subpassCount` to the count of subpasses added previously by
+         *      this function plus @cpp 1 @ce
+         * -    `pSubpasses` to an array containing all subpass descriptions
+         *      added previously by this function together with @p subpass;
+         *      ownership of associated @ref SubpassDescription state is moved
+         *      to the @ref RenderPassCreateInfo instance
          */
         RenderPassCreateInfo& addSubpass(SubpassDescription&& subpass);
 
@@ -991,8 +1031,14 @@ class MAGNUM_VK_EXPORT RenderPassCreateInfo {
          * @brief Set subpass dependencies
          * @return Reference to self (for method chaining)
          *
-         * ubsequent calls to this function will *replace* the previous set,
+         * Subsequent calls to this function will *replace* the previous set,
          * not append to it.
+         *
+         * The following @type_vk{RenderPassCreateInfo2} fields are set by this
+         * function:
+         *
+         * -    `dependencyCount` to @cpp dependencies.size() @ce
+         * -    `pDependencies` to a copy of @p dependencies
          */
         RenderPassCreateInfo& setDependencies(Containers::ArrayView<const SubpassDependency> dependencies);
         /** @overload */