[PATCH v2 0/1] MR110: vkd3d-shader: Make documentation for "messages" parameters self contained.

[Giovanni Mascellani (＠giomasce)]

Otherwise it's not clear which clauses in vkd3d_shader_compile() really
apply to other functions. For example, many of the functions currently
refering to vkd3d_shader_compile() don't even take a vkd3d_shader_compile_info
parameter.

--
  v2: vkd3d-shader: Make documentation for "messages" parameters self contained.
 
https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/110

[PATCH v2 1/1] vkd3d-shader: Make documentation for "messages" parameters self contained.

[Giovanni Mascellani]

From: Giovanni Mascellani <gmascellani(a)codeweavers.com>

Otherwise it's not clear which clauses in vkd3d_shader_compile() really
apply to other functions. For example, many of the functions currently
refering to vkd3d_shader_compile() don't even take a vkd3d_shader_compile_info
parameter.
---
 include/vkd3d_shader.h | 71 +++++++++++++++++++++++++++++++++---------
 1 file changed, 57 insertions(+), 14 deletions(-)

diff --git a/include/vkd3d_shader.h b/include/vkd3d_shader.h
index 51d03e28..fff2abe0 100644
--- a/include/vkd3d_shader.h
+++ b/include/vkd3d_shader.h
@@ -1699,8 +1699,13 @@ VKD3D_SHADER_API void vkd3d_shader_free_shader_code(struct vkd3d_shader_code *co
  * \param messages Optional output location for error or informational messages
  * produced by the compiler.
  * \n
- * This parameter behaves identically to the \a messages parameter of
- * vkd3d_shader_compile().
+ * This string is null-terminated and UTF-8 encoded.
+ * \n
+ * The messages are allocated by vkd3d-shader and should be freed with
+ * vkd3d_shader_free_messages() when no longer needed.
+ * \n
+ * If no compilation messages are produced by the compiler, this parameter may
+ * receive NULL instead of a valid string pointer.
  *
  * \return A member of \ref vkd3d_result.
  */
@@ -1737,8 +1742,13 @@ VKD3D_SHADER_API void vkd3d_shader_free_root_signature(
  * \param messages Optional output location for error or informational messages
  * produced by the compiler.
  * \n
- * This parameter behaves identically to the \a messages parameter of
- * vkd3d_shader_compile().
+ * This string is null-terminated and UTF-8 encoded.
+ * \n
+ * The messages are allocated by vkd3d-shader and should be freed with
+ * vkd3d_shader_free_messages() when no longer needed.
+ * \n
+ * If no compilation messages are produced by the compiler, this parameter may
+ * receive NULL instead of a valid string pointer.
  *
  * \return A member of \ref vkd3d_result.
  */
@@ -1787,8 +1797,17 @@ VKD3D_SHADER_API int vkd3d_shader_convert_root_signature(struct vkd3d_shader_ver
  * \param messages Optional output location for error or informational messages
  * produced by the compiler.
  * \n
- * This parameter behaves identically to the \a messages parameter of
- * vkd3d_shader_compile().
+ * This string is null-terminated and UTF-8 encoded.
+ * \n
+ * The messages are allocated by vkd3d-shader and should be freed with
+ * vkd3d_shader_free_messages() when no longer needed.
+ * \n
+ * The messages returned can be regulated with the \a log_level member of struct
+ * vkd3d_shader_compile_info. Regardless of the requested level, if this
+ * parameter is NULL, no compilation messages will be returned.
+ * \n
+ * If no compilation messages are produced by the compiler, this parameter may
+ * receive NULL instead of a valid string pointer.
  *
  * \return A member of \ref vkd3d_result.
  */
@@ -1824,8 +1843,13 @@ VKD3D_SHADER_API void vkd3d_shader_free_scan_descriptor_info(
  * \param messages Optional output location for error or informational messages
  * produced by the compiler.
  * \n
- * This parameter behaves identically to the \a messages parameter of
- * vkd3d_shader_compile().
+ * This string is null-terminated and UTF-8 encoded.
+ * \n
+ * The messages are allocated by vkd3d-shader and should be freed with
+ * vkd3d_shader_free_messages() when no longer needed.
+ * \n
+ * If no compilation messages are produced by the compiler, this parameter may
+ * receive NULL instead of a valid string pointer.
  *
  * \return A member of \ref vkd3d_result.
  */
@@ -1883,8 +1907,17 @@ VKD3D_SHADER_API void vkd3d_shader_free_shader_signature(struct vkd3d_shader_sig
  * \param messages Optional output location for error or informational messages
  * produced by the compiler.
  * \n
- * This parameter behaves identically to the \a messages parameter of
- * vkd3d_shader_compile().
+ * This string is null-terminated and UTF-8 encoded.
+ * \n
+ * The messages are allocated by vkd3d-shader and should be freed with
+ * vkd3d_shader_free_messages() when no longer needed.
+ * \n
+ * The messages returned can be regulated with the \a log_level member of struct
+ * vkd3d_shader_compile_info. Regardless of the requested level, if this
+ * parameter is NULL, no compilation messages will be returned.
+ * \n
+ * If no compilation messages are produced by the compiler, this parameter may
+ * receive NULL instead of a valid string pointer.
  *
  * \return A member of \ref vkd3d_result.
  *
@@ -1936,8 +1969,13 @@ VKD3D_SHADER_API void vkd3d_shader_free_dxbc(struct vkd3d_shader_dxbc_desc *dxbc
  * \param messages Optional output location for error or informational messages
  * produced by the parser.
  * \n
- * This parameter behaves identically to the \a messages parameter of
- * vkd3d_shader_compile().
+ * This string is null-terminated and UTF-8 encoded.
+ * \n
+ * The messages are allocated by vkd3d-shader and should be freed with
+ * vkd3d_shader_free_messages() when no longer needed.
+ * \n
+ * If no compilation messages are produced by the compiler, this parameter may
+ * receive NULL instead of a valid string pointer.
  *
  * \return A member of \ref vkd3d_result.
  *
@@ -1964,8 +2002,13 @@ VKD3D_SHADER_API int vkd3d_shader_parse_dxbc(const struct vkd3d_shader_code *dxb
  * \param messages Optional output location for error or informational messages
  * produced by the serialiser.
  * \n
- * This parameter behaves identically to the \a messages parameter of
- * vkd3d_shader_compile().
+ * This string is null-terminated and UTF-8 encoded.
+ * \n
+ * The messages are allocated by vkd3d-shader and should be freed with
+ * vkd3d_shader_free_messages() when no longer needed.
+ * \n
+ * If no compilation messages are produced by the compiler, this parameter may
+ * receive NULL instead of a valid string pointer.
  *
  * \return A member of \ref vkd3d_result.
  *
-- 
GitLab

https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/110