Giovanni Mascellani : vkd3d-shader: Make documentation for "messages" parameters self contained.

Module: vkd3d Branch: master Commit: 6ccde9e82c00393f212ddb1934d97eb8858ba331 URL: https://gitlab.winehq.org/wine/vkd3d/-/commit/6ccde9e82c00393f212ddb1934d97… Author: Giovanni Mascellani <gmascellani(a)codeweavers.com> Date: Fri Feb 24 13:18:49 2023 +0100 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. --- include/vkd3d_shader.h | 93 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 68 insertions(+), 25 deletions(-) diff --git a/include/vkd3d_shader.h b/include/vkd3d_shader.h index 51d03e28..ee8ce8d0 100644 --- a/include/vkd3d_shader.h +++ b/include/vkd3d_shader.h @@ -1648,7 +1648,7 @@ VKD3D_SHADER_API const enum vkd3d_shader_target_type *vkd3d_shader_get_supported * 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 + * If no messages are produced by the compiler, this parameter may * receive NULL instead of a valid string pointer. * * \return A member of \ref vkd3d_result. @@ -1697,10 +1697,15 @@ VKD3D_SHADER_API void vkd3d_shader_free_shader_code(struct vkd3d_shader_code *co * needed. * * \param messages Optional output location for error or informational messages - * produced by the compiler. + * 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 messages are produced by the parser, this parameter may + * receive NULL instead of a valid string pointer. * * \return A member of \ref vkd3d_result. */ @@ -1735,10 +1740,15 @@ VKD3D_SHADER_API void vkd3d_shader_free_root_signature( * vkd3d_shader_free_shader_code() when no longer needed. * * \param messages Optional output location for error or informational messages - * produced by the compiler. + * produced by the serializer. * \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 messages are produced by the serializer, this parameter may + * receive NULL instead of a valid string pointer. * * \return A member of \ref vkd3d_result. */ @@ -1785,10 +1795,19 @@ VKD3D_SHADER_API int vkd3d_shader_convert_root_signature(struct vkd3d_shader_ver * depending on their structure type. * * \param messages Optional output location for error or informational messages - * produced by the compiler. + * 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 + * 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 messages are produced by the parser, this parameter may + * receive NULL instead of a valid string pointer. * * \return A member of \ref vkd3d_result. */ @@ -1822,10 +1841,15 @@ VKD3D_SHADER_API void vkd3d_shader_free_scan_descriptor_info( * needed. * * \param messages Optional output location for error or informational messages - * produced by the compiler. + * 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 messages are produced by the parser, this parameter may + * receive NULL instead of a valid string pointer. * * \return A member of \ref vkd3d_result. */ @@ -1881,10 +1905,19 @@ VKD3D_SHADER_API void vkd3d_shader_free_shader_signature(struct vkd3d_shader_sig * vkd3d_shader_free_shader_code() when no longer needed. * * \param messages Optional output location for error or informational messages - * produced by the compiler. + * produced by the preprocessor. * \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 messages are produced by the preprocessor, 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 messages are produced by the parser, this parameter may + * receive NULL instead of a valid string pointer. * * \return A member of \ref vkd3d_result. * @@ -1947,25 +1985,30 @@ VKD3D_SHADER_API int vkd3d_shader_parse_dxbc(const struct vkd3d_shader_code *dxb uint32_t flags, struct vkd3d_shader_dxbc_desc *desc, char **messages); /** - * Serialise a DXBC description into a blob stored in a vkd3d_shader_code + * Serialize a DXBC description into a blob stored in a vkd3d_shader_code * structure. * - * \param section_count The number of DXBC sections to serialise. + * \param section_count The number of DXBC sections to serialize. * * \param sections An array of vkd3d_shader_dxbc_section_desc structures - * to serialise. + * to serialize. * * \param dxbc A pointer to a vkd3d_shader_code structure in which the - * serialised blob will be stored. + * serialized blob will be stored. * \n * The output blob is allocated by vkd3d-shader and should be freed with * vkd3d_shader_free_shader_code() when no longer needed. * * \param messages Optional output location for error or informational messages - * produced by the serialiser. + * produced by the serializer. * \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 messages are produced by the serializer, this parameter may + * receive NULL instead of a valid string pointer. * * \return A member of \ref vkd3d_result. *