Updated documentation for IArchiver and related structs

Author: TheMostDiligent

Graphics/Archiver/interface/Archiver.h

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2024 Diligent Graphics LLC
+ *  Copyright 2019-2025 Diligent Graphics LLC
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -94,7 +94,7 @@ DILIGENT_BEGIN_INTERFACE(IArchiver, IObject)
     /// \param [out] ppBlob         - memory location where a pointer to the data blob will be stored.
 
     /// \note
-    ///     The method is *not* thread-safe and must not be called from multiple threads simultaneously.
+    ///     The method is *not* thread-safe and **must not** be called from multiple threads simultaneously.
     VIRTUAL Bool METHOD(SerializeToBlob)(THIS_
                                          Uint32      ContentVersion,
                                          IDataBlob** ppBlob) PURE;
@@ -105,7 +105,7 @@ DILIGENT_BEGIN_INTERFACE(IArchiver, IObject)
     /// \param [out] pStream        - a pointer to the stream to write the archive to.
 
     /// \note
-    ///     The method is *not* thread-safe and must not be called from multiple threads simultaneously.
+    ///     The method is *not* thread-safe and **must not** be called from multiple threads simultaneously.
     VIRTUAL Bool METHOD(SerializeToStream)(THIS_
                                            Uint32       ContentVersion,
                                            IFileStream* pStream) PURE;
@@ -114,11 +114,12 @@ DILIGENT_BEGIN_INTERFACE(IArchiver, IObject)
 
     /// \param [in] pShader - a pointer to the shader to add to the archive.
     ///
-    /// \return     true if the shader was added successfully, and false otherwise.
+    /// \return     `true` if the shader was added successfully, and `false` otherwise.
     ///
     /// \note
     ///     Shader object pointed to by pShader must have been created by the serialization device.
     ///
+    /// \note
     ///     Multiple shaders may be packed into the same archive as long as they use unique names.
     ///
     ///     The method is thread-safe and may be called from multiple threads simultaneously.
@@ -129,11 +130,12 @@ DILIGENT_BEGIN_INTERFACE(IArchiver, IObject)
 
     /// \param [in] pPSO - a pointer to the pipeline state to add to the archive.
     ///
-    /// \return     true if the pipeline state was added successfully, and false otherwise.
+    /// \return     `true` if the pipeline state was added successfully, and `false` otherwise.
     ///
     /// \note
     ///     Pipeline state object pointed to by pPSO must have been created by the serialization device.
     ///
+    /// \note
     ///     Multiple pipeline states may be packed into the same archive as long as they use unique names.
     ///     All dependent objects (render pass, resource signatures, shaders) will be added to the archive
     ///     and must also use unique names.
@@ -147,11 +149,12 @@ DILIGENT_BEGIN_INTERFACE(IArchiver, IObject)
 
     /// \param [in] pSignature - a pointer to the resource signature to add to the archive.
     ///
-    /// \return     true if the signature was added successfully, and false otherwise.
+    /// \return     `true` if the signature was added successfully, and `false` otherwise.
     ///
     /// \note
     ///     Pipeline resource signature pointed to by pSignature must have been created by the serialization device.
     ///
+    /// \note
     ///     Multiple PSOs and signatures may be packed into the same archive as long as they use distinct names.
     ///
     ///     The method is thread-safe and may be called from multiple threads simultaneously.
@@ -166,8 +169,8 @@ DILIGENT_BEGIN_INTERFACE(IArchiver, IObject)
     /// \param [in] ShaderName - Name of the shader object to retrieve.
     /// \return     A pointer to the shader object, or null if the object with that name was not added.
     ///
-    /// \ note      The method does *not* increment the reference counter of the returned object,
-    ///             so the application must not call Release() unless it also explicitly calls AddRef().
+    /// \note       The method does *not* increment the reference counter of the returned object,
+    ///             so the application **must not** call Release() unless it also explicitly calls AddRef().
     VIRTUAL IShader* METHOD(GetShader)(THIS_
                                        const char* ShaderName) PURE;
 
@@ -177,8 +180,8 @@ DILIGENT_BEGIN_INTERFACE(IArchiver, IObject)
     /// \param [in] PSOName - Name of the pipeline state to retrieve.
     /// \return     A pointer to the pipeline state object, or null if the object with that name was not added.
     ///
-    /// \ note      The method does *not* increment the reference counter of the returned object,
-    ///             so the application must not call Release() unless it also explicitly calls AddRef().
+    /// \note       The method does *not* increment the reference counter of the returned object,
+    ///             so the application **must not** call Release() unless it also explicitly calls AddRef().
     VIRTUAL IPipelineState* METHOD(GetPipelineState)(THIS_
                                                      PIPELINE_TYPE PSOType,
                                                      const char*   PSOName) PURE;
@@ -188,8 +191,8 @@ DILIGENT_BEGIN_INTERFACE(IArchiver, IObject)
     /// \param [in] PRSName - Name of the pipeline resource signature to retrieve.
     /// \return     A pointer to the the pipeline resource signature object, or null if the object with that name was not added.
     ///
-    /// \ note      The method does *not* increment the reference counter of the returned object,
-    ///             so the application must not call Release() unless it also explicitly calls AddRef().
+    /// \note      The method does *not* increment the reference counter of the returned object,
+    ///             so the application **must not** call Release() unless it also explicitly calls AddRef().
     VIRTUAL IPipelineResourceSignature* METHOD(GetPipelineResourceSignature)(THIS_
                                                                              const char* PRSName) PURE;
 };

Graphics/Archiver/interface/ArchiverFactory.h

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2024 Diligent Graphics LLC
+ *  Copyright 2019-2025 Diligent Graphics LLC
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -107,7 +107,7 @@ struct SerializationDeviceGLInfo
     ///             When OptimizeShaders is set to true, the archiver will optimize the shader
     ///             source code for run-time loading performance.
     ///
-    ///             Technical details: the archiver will compile the shader source code to SPIRV
+    /// \remarks    Technical details: the archiver will compile the shader source code to SPIRV
     ///             with GLSLang and then translate SPIRV back to GLSL using SPIRV-Cross.
     ///             The resulting GLSL code will be much more compact and will be stored in the
     ///             archive instead of the original source code.
@@ -160,7 +160,6 @@ struct SerializationDeviceVkInfo
         return !(*this == RHS);
     }
 #endif
-
 };
 typedef struct SerializationDeviceVkInfo SerializationDeviceVkInfo;
 
@@ -201,13 +200,15 @@ typedef struct SerializationDeviceMtlInfo SerializationDeviceMtlInfo;
 struct SerializationDeviceCreateInfo
 {
     /// Device info, contains enabled device features.
-    /// Can be used to validate shader, render pass, resource signature and pipeline state.
+
+    /// Can be used to validate shaders, render passes, resource signatures and pipeline states.
     ///
     /// \note For OpenGL that does not support separable programs, disable the SeparablePrograms feature.
     RenderDeviceInfo    DeviceInfo;
 
     /// Adapter info, contains device parameters.
-    /// Can be used to validate shader, render pass, resource signature and pipeline state.
+
+    /// Can be used to validate shaders, render passes, resource signatures and pipeline states.
     GraphicsAdapterInfo AdapterInfo;
 
     /// Direct3D11 attributes, see Diligent::SerializationDeviceD3D11Info.
@@ -229,14 +230,14 @@ struct SerializationDeviceCreateInfo
     IThreadPool* pAsyncShaderCompilationThreadPool DEFAULT_INITIALIZER(nullptr);
 
     /// The maximum number of threads that can be used to compile shaders.
-    ///
-    /// \remarks    If pAsyncShaderCompilationThreadPool is null, this value is used to define the number of threads in
-    ///             the default thread pool.
-    ///             If the value is 0xFFFFFFFF, the number of threads will be determined automatically.
-    ///             If the value is 0, the default thread pool will not be created.
+
+    /// If `pAsyncShaderCompilationThreadPool` is `null`, this value is used to define the number of threads in
+    /// the default thread pool.
+    /// If the value is `0xFFFFFFFF`, the number of threads will be determined automatically.
+    /// If the value is `0`, the default thread pool will not be created.
     ///             
-    ///             If pAsyncShaderCompilationThreadPool is not null, the value is ignored as the user-provided
-    ///             thread pool is used instead.
+    /// If `pAsyncShaderCompilationThreadPool` is not `null`, the value is ignored as the user-provided
+    /// thread pool is used instead.
     Uint32 NumAsyncShaderCompilationThreads DEFAULT_INITIALIZER(0);
 
 #if DILIGENT_CPP_INTERFACE
@@ -289,7 +290,7 @@ DILIGENT_BEGIN_INTERFACE(IArchiverFactory, IObject)
     /// \param [in]  pSrcArchive  - Source archive from which device specific-data will be removed.
     /// \param [in]  DeviceFlags  - Combination of device types that will be removed.
     /// \param [out] ppDstArchive - Memory address where a pointer to the new archive will be written.
-    /// \return     true if the device-specific data was successfully removed, and false otherwise.
+    /// \return     `true` if the device-specific data was successfully removed, and `false` otherwise.
     VIRTUAL Bool METHOD(RemoveDeviceData)(THIS_
                                           const IDataBlob*          pSrcArchive,
                                           ARCHIVE_DEVICE_DATA_FLAGS DeviceFlags,
@@ -302,7 +303,7 @@ DILIGENT_BEGIN_INTERFACE(IArchiverFactory, IObject)
     /// \param [in]  DeviceFlags    - Combination of device types that will be copied.
     /// \param [in]  pDeviceArchive - Archive that contains the same common data and additional device-specific data.
     /// \param [out] ppDstArchive   - Memory address where a pointer to the new archive will be written.
-    /// \return     true if the device-specific data was successfully added, and false otherwise.
+    /// \return     `true` if the device-specific data was successfully added, and `false` otherwise.
     VIRTUAL Bool METHOD(AppendDeviceData)(THIS_
                                           const IDataBlob*          pSrcArchive,
                                           ARCHIVE_DEVICE_DATA_FLAGS DeviceFlags,
@@ -313,9 +314,9 @@ DILIGENT_BEGIN_INTERFACE(IArchiverFactory, IObject)
     /// Merges multiple archives into one.
 
     /// \param [in]  ppSrcArchives   - An array of pointers to the source archives.
-    /// \param [in]  NumSrcArchives  - The number of elements in ppArchives array.
+    /// \param [in]  NumSrcArchives  - The number of elements in `ppArchives` array.
     /// \param [out] ppDstArchive    - Memory address where a pointer to the merged archive will be written.
-    /// \return     true if the archives were successfully merged, and false otherwise.
+    /// \return     `true` if the archives were successfully merged, and `false` otherwise.
     VIRTUAL Bool METHOD(MergeArchives)(THIS_
                                        const IDataBlob* ppSrcArchives[],
                                        Uint32           NumSrcArchives,

Graphics/Archiver/interface/SerializationDevice.h

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2023 Diligent Graphics LLC
+ *  Copyright 2019-2025 Diligent Graphics LLC
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -56,6 +56,7 @@ static DILIGENT_CONSTEXPR INTERFACE_ID IID_SerializationDevice =
 struct ShaderArchiveInfo
 {
     /// Bitset of Diligent::ARCHIVE_DEVICE_DATA_FLAGS.
+
     /// Specifies for which backends the shader data will be serialized.
     ARCHIVE_DEVICE_DATA_FLAGS DeviceFlags DEFAULT_INITIALIZER(ARCHIVE_DEVICE_DATA_FLAG_NONE);
 };
@@ -65,6 +66,7 @@ typedef struct ShaderArchiveInfo ShaderArchiveInfo;
 struct ResourceSignatureArchiveInfo
 {
     /// Bitset of Diligent::ARCHIVE_DEVICE_DATA_FLAGS.
+
     /// Specifies for which backends the resource signature data will be serialized.
     ARCHIVE_DEVICE_DATA_FLAGS DeviceFlags DEFAULT_INITIALIZER(ARCHIVE_DEVICE_DATA_FLAG_NONE);
 };
@@ -77,6 +79,7 @@ struct PipelineStateArchiveInfo
     PSO_ARCHIVE_FLAGS PSOFlags DEFAULT_INITIALIZER(PSO_ARCHIVE_FLAG_NONE);
 
     /// Bitset of Diligent::ARCHIVE_DEVICE_DATA_FLAGS.
+
     /// Specifies for which backends the pipeline state data will be serialized.
     ARCHIVE_DEVICE_DATA_FLAGS DeviceFlags DEFAULT_INITIALIZER(ARCHIVE_DEVICE_DATA_FLAG_NONE);
 };
@@ -86,23 +89,27 @@ typedef struct PipelineStateArchiveInfo PipelineStateArchiveInfo;
 /// Contains attributes to calculate pipeline resource bindings
 struct PipelineResourceBindingAttribs
 {
-    /// An array of ResourceSignaturesCount shader resource signatures that
+    /// An array of `ResourceSignaturesCount` shader resource signatures that
     /// define the layout of shader resources in this pipeline state object.
+
     /// See Diligent::IPipelineResourceSignature.
     IPipelineResourceSignature** ppResourceSignatures      DEFAULT_INITIALIZER(nullptr);
 
-    /// The number of elements in ppResourceSignatures array.
+    /// The number of elements in `ppResourceSignatures` array.
     Uint32                       ResourceSignaturesCount   DEFAULT_INITIALIZER(0);
 
     /// The number of render targets, only for graphics pipeline.
+
     /// \note Required for Direct3D11 graphics pipelines that use UAVs.
     Uint32                       NumRenderTargets  DEFAULT_INITIALIZER(0);
 
     /// The number of vertex buffers, only for graphics pipeline.
+
     /// \note Required for Metal.
     Uint32                       NumVertexBuffers  DEFAULT_INITIALIZER(0);
 
     /// Vertex buffer names.
+
     /// \note Required for Metal.
     Char const* const*           VertexBufferNames DEFAULT_INITIALIZER(nullptr);
 
@@ -260,22 +267,22 @@ DILIGENT_BEGIN_INTERFACE(ISerializationDevice, IRenderDevice)
                                          IRenderDevice* pDevice) PURE;
 
 #if DILIGENT_CPP_INTERFACE
-    /// Overloaded alias for CreateGraphicsPipelineState.
+    /// Overloaded alias for ISerializationDevice::CreateGraphicsPipelineState.
     void CreatePipelineState(const GraphicsPipelineStateCreateInfo& CI, const PipelineStateArchiveInfo& ArchiveInfo, IPipelineState** ppPipelineState)
     {
         CreateGraphicsPipelineState(CI, ArchiveInfo, ppPipelineState);
     }
-    /// Overloaded alias for CreateComputePipelineState.
+    /// Overloaded alias for ISerializationDevice::CreateComputePipelineState.
     void CreatePipelineState(const ComputePipelineStateCreateInfo& CI, const PipelineStateArchiveInfo& ArchiveInfo, IPipelineState** ppPipelineState)
     {
         CreateComputePipelineState(CI, ArchiveInfo, ppPipelineState);
     }
-    /// Overloaded alias for CreateRayTracingPipelineState.
+    /// Overloaded alias for ISerializationDevice::CreateRayTracingPipelineState.
     void CreatePipelineState(const RayTracingPipelineStateCreateInfo& CI, const PipelineStateArchiveInfo& ArchiveInfo, IPipelineState** ppPipelineState)
     {
         CreateRayTracingPipelineState(CI, ArchiveInfo, ppPipelineState);
     }
-    /// Overloaded alias for CreateTilePipelineState.
+    /// Overloaded alias for ISerializationDevice::CreateTilePipelineState.
     void CreatePipelineState(const TilePipelineStateCreateInfo& CI, const PipelineStateArchiveInfo& ArchiveInfo, IPipelineState** ppPipelineState)
     {
         CreateTilePipelineState(CI, ArchiveInfo, ppPipelineState);

Graphics/Archiver/interface/SerializedShader.h

@@ -1,5 +1,5 @@
 /*
- *  Copyright 2019-2023 Diligent Graphics LLC
+ *  Copyright 2019-2025 Diligent Graphics LLC
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -51,7 +51,7 @@ static DILIGENT_CONSTEXPR INTERFACE_ID IID_SerializedShader =
 DILIGENT_BEGIN_INTERFACE(ISerializedShader, IShader)
 {
     /// Returns a device-specific shader for the given render device type.
-    ///
+
     /// \note   In order for the returned shader object to be fully initialized
     ///         and suitable for use in rendering commands, a corresponding render
     ///         device must have been initialized in the serialization device through