[PATCH v2 0/1] MR110: vkd3d-shader: Make documentation for "messages" parameters self contained.
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.
From: Giovanni Mascellani gmascellani@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. *
-
Giovanni Mascellani -
Giovanni Mascellani (＠giomasce)