From c5c24a445ed50ec0b193fb4156be5b2f9b4c2acb Mon Sep 17 00:00:00 2001 From: Mark Callow <2244683+MarkCallow@users.noreply.github.com> Date: Fri, 17 Mar 2023 10:58:56 +0900 Subject: [PATCH] Fix warnings newly raised by Doxygen 1.9.6. (#676) @refs and @copy*s to "class" members from outside a class must now use fully qualified "class" names. Hides display of these "class" names in the function list at the top of a module's page. They are still displayed in the Modules section of the ToC due to what looks like a Doxygen bug. Ignores [Kk][Tt][Xx]{,_} prefixes when building alphabetical indexes so everything does not appear under K. --- cmake/docs.cmake | 7 ++++++- include/ktx.h | 28 ++++++++++++++-------------- lib/glloader.c | 24 +++++++++++++++++++----- lib/texture2.c | 2 +- lib/vkloader.c | 2 ++ 5 files changed, 42 insertions(+), 21 deletions(-) diff --git a/cmake/docs.cmake b/cmake/docs.cmake index bbfdb68bab..529eb438ff 100644 --- a/cmake/docs.cmake +++ b/cmake/docs.cmake @@ -18,7 +18,6 @@ set( DOXYGEN_HTML_TIMESTAMP YES ) set( DOXYGEN_DISABLE_INDEX YES ) set( DOXYGEN_GENERATE_TREEVIEW YES ) set( DOXYGEN_GENERATE_LATEX NO ) -# set( DOXYGEN_PAPER_TYPE a4wide ) # note: invalid value! set( DOXYGEN_GENERATE_MAN YES ) @@ -40,7 +39,13 @@ function( CreateDocLibKTX ) set( DOXYGEN_EXCLUDE lib/uthash.h ) set( DOXYGEN_EXCLUDE_PATTERNS ktxint.h ) set( DOXYGEN_EXAMPLE_PATH examples lib ) + # This does not hide the scope (class) names in the Modules list + # in the ToC. See https://github.com/doxygen/doxygen/issues/9921. + set( DOXYGEN_HIDE_SCOPE_NAMES YES ) set( DOXYGEN_HTML_OUTPUT html/libktx ) + # Order is important here. '_' suffixed prefices must come first + # otherwise the non-suffixed is stripped first leaving just '_'. + set( DOXYGEN_IGNORE_PREFIX KTX_;ktx_;KTX;ktx ) set( DOXYGEN_MAN_LINKS YES ) set( DOXYGEN_MACRO_EXPANSION YES ) set( DOXYGEN_EXPAND_ONLY_PREDEF YES ) diff --git a/include/ktx.h b/include/ktx.h index 27fe5f93c7..60e94f01b5 100644 --- a/include/ktx.h +++ b/include/ktx.h @@ -519,7 +519,7 @@ typedef KTX_error_code /** * @~English * @brief Helper for calling the Destroy virtual method of a ktxTexture. - * @copydoc ktxTexture2_Destroy + * @copydoc ktxTexture2.ktxTexture2_Destroy */ #define ktxTexture_Destroy(This) (This)->vtbl->Destroy(This) @@ -527,7 +527,7 @@ typedef KTX_error_code * @~English * @brief Helper for calling the GetImageOffset virtual method of a * ktxTexture. - * @copydoc ktxTexture2_GetImageOffset + * @copydoc ktxTexture2.ktxTexture2_GetImageOffset */ #define ktxTexture_GetImageOffset(This, level, layer, faceSlice, pOffset) \ (This)->vtbl->GetImageOffset(This, level, layer, faceSlice, pOffset) @@ -538,7 +538,7 @@ typedef KTX_error_code * * For a ktxTexture1 this will always return the value of This->dataSize. * - * @copydetails ktxTexture2_GetDataSizeUncompressed + * @copydetails ktxTexture2.ktxTexture2_GetDataSizeUncompressed */ #define ktxTexture_GetDataSizeUncompressed(This) \ (This)->vtbl->GetDataSizeUncompressed(This) @@ -546,7 +546,7 @@ typedef KTX_error_code /** * @~English * @brief Helper for calling the GetImageSize virtual method of a ktxTexture. - * @copydoc ktxTexture2_GetImageSize + * @copydoc ktxTexture2.ktxTexture2_GetImageSize */ #define ktxTexture_GetImageSize(This, level) \ (This)->vtbl->GetImageSize(This, level) @@ -554,7 +554,7 @@ typedef KTX_error_code /** * @~English * @brief Helper for calling the IterateLevels virtual method of a ktxTexture. - * @copydoc ktxTexture2_IterateLevels + * @copydoc ktxTexture2.ktxTexture2_IterateLevels */ #define ktxTexture_IterateLevels(This, iterCb, userdata) \ (This)->vtbl->IterateLevels(This, iterCb, userdata) @@ -563,7 +563,7 @@ typedef KTX_error_code * @~English * @brief Helper for calling the IterateLoadLevelFaces virtual method of a * ktxTexture. - * @copydoc ktxTexture2_IterateLoadLevelFaces + * @copydoc ktxTexture2.ktxTexture2_IterateLoadLevelFaces */ #define ktxTexture_IterateLoadLevelFaces(This, iterCb, userdata) \ (This)->vtbl->IterateLoadLevelFaces(This, iterCb, userdata) @@ -571,7 +571,7 @@ typedef KTX_error_code /** * @~English * @brief Helper for calling the LoadImageData virtual method of a ktxTexture. - * @copydoc ktxTexture2_LoadImageData + * @copydoc ktxTexture2.ktxTexture2_LoadImageData */ #define ktxTexture_LoadImageData(This, pBuffer, bufSize) \ (This)->vtbl->LoadImageData(This, pBuffer, bufSize) @@ -579,7 +579,7 @@ typedef KTX_error_code /** * @~English * @brief Helper for calling the NeedsTranscoding virtual method of a ktxTexture. - * @copydoc ktxTexture2_NeedsTranscoding + * @copydoc ktxTexture2.ktxTexture2_NeedsTranscoding */ #define ktxTexture_NeedsTranscoding(This) (This)->vtbl->NeedsTranscoding(This) @@ -587,7 +587,7 @@ typedef KTX_error_code * @~English * @brief Helper for calling the SetImageFromMemory virtual method of a * ktxTexture. - * @copydoc ktxTexture2_SetImageFromMemory + * @copydoc ktxTexture2.ktxTexture2_SetImageFromMemory */ #define ktxTexture_SetImageFromMemory(This, level, layer, faceSlice, \ src, srcSize) \ @@ -597,7 +597,7 @@ typedef KTX_error_code * @~English * @brief Helper for calling the SetImageFromStdioStream virtual method of a * ktxTexture. - * @copydoc ktxTexture2_SetImageFromStdioStream + * @copydoc ktxTexture2.ktxTexture2_SetImageFromStdioStream */ #define ktxTexture_SetImageFromStdioStream(This, level, layer, faceSlice, \ src, srcSize) \ @@ -608,7 +608,7 @@ typedef KTX_error_code * @~English * @brief Helper for calling the WriteToStdioStream virtual method of a * ktxTexture. - * @copydoc ktxTexture2_WriteToStdioStream + * @copydoc ktxTexture2.ktxTexture2_WriteToStdioStream */ #define ktxTexture_WriteToStdioStream(This, dstsstr) \ (This)->vtbl->WriteToStdioStream(This, dstsstr) @@ -617,7 +617,7 @@ typedef KTX_error_code * @~English * @brief Helper for calling the WriteToNamedfile virtual method of a * ktxTexture. - * @copydoc ktxTexture2_WriteToNamedFile + * @copydoc ktxTexture2.ktxTexture2_WriteToNamedFile */ #define ktxTexture_WriteToNamedFile(This, dstname) \ (This)->vtbl->WriteToNamedFile(This, dstname) @@ -625,7 +625,7 @@ typedef KTX_error_code /** * @~English * @brief Helper for calling the WriteToMemory virtual method of a ktxTexture. - * @copydoc ktxTexture2_WriteToMemory + * @copydoc ktxTexture2.ktxTexture2_WriteToMemory */ #define ktxTexture_WriteToMemory(This, ppDstBytes, pSize) \ (This)->vtbl->WriteToMemory(This, ppDstBytes, pSize) @@ -633,7 +633,7 @@ typedef KTX_error_code /** * @~English * @brief Helper for calling the WriteToStream virtual method of a ktxTexture. - * @copydoc ktxTexture2_WriteToStream + * @copydoc ktxTexture2.ktxTexture2_WriteToStream */ #define ktxTexture_WriteToStream(This, dststr) \ (This)->vtbl->WriteToStream(This, dststr) diff --git a/lib/glloader.c b/lib/glloader.c index 067b597916..1aa92090e4 100644 --- a/lib/glloader.c +++ b/lib/glloader.c @@ -40,11 +40,23 @@ * @{ */ +/* + * N.B. As of Doxygen 1.9.6 non-class members must use fully qualified + * names with @ref and @copy* references to classes. This means prefixing + * a reference with the name of the (pseudo-)class of which it is a member. + * We use @memberof to improve the index and toc for the doc for our + * pseudo classes so we need to prefix. Since we don't want, e.g., + * ktxTexture1::ktxTexture1_GLUpload appearing in the documentation we have + * to explicitly provide the link text making references very long-winded. + * Sigh! + */ + /** * @example glloader.c * This is an example of using the low-level ktxTexture API to create and load * an OpenGL texture. It is a fragment of the code used by - * @ref ktxTexture1_GLUpload and @ref ktxTexture2_GLUpload functions. + * @ref ktxTexture1.ktxTexture1\_GLUpload "ktxTexture1_GLUpload" and + * @ref ktxTexture2.ktxTexture2\_GLUpload "ktxTexture2_GLUpload". * * @code * #include @@ -54,10 +66,12 @@ * across all images. * @snippet this cbdata * - * One of these callbacks, selected by @ref ktxTexture1_GLUpload or - * @ref ktxTexture2_GLUpload based on the dimensionality and arrayness of the - * texture, is called from @ref ktxTexture_IterateLevelFaces to upload the - * texture data to OpenGL. + * One of these callbacks, selected by @ref + * ktxTexture1.ktxTexture1\_GLUpload "ktxTexture1_GLUpload" or + * @ref ktxTexture2.ktxTexture2\_GLUpload "ktxTexture2_GLUpload" based on the + * dimensionality and arrayness of the texture, is called from + * @ref ktxTexture.ktxTexture_IterateLevelFaces + * "ktxTexture_IterateLevelFaces" to upload the texture data to OpenGL. * @snippet this imageCallbacks * * This function creates the GL texture object and sets up the callbacks to diff --git a/lib/texture2.c b/lib/texture2.c index 3b958e551e..effe7862ba 100644 --- a/lib/texture2.c +++ b/lib/texture2.c @@ -1870,7 +1870,7 @@ ktxTexture2_GetImageSize(ktxTexture2* This, ktx_uint32_t level) } /** - * @memberof ktxTexture + * @memberof ktxTexture2 * @~English * @brief Iterate over the mip levels in a ktxTexture2 object. * diff --git a/lib/vkloader.c b/lib/vkloader.c index 411963974b..5b0fca98b4 100644 --- a/lib/vkloader.c +++ b/lib/vkloader.c @@ -190,8 +190,10 @@ ktxVulkanDeviceInfo_Construct(ktxVulkanDeviceInfo* This, } /** + * @memberof ktxVulkanDeviceInfo * @copydoc ktxVulkanDeviceInfo_Construct * + * @~English * @param instance handle of the Vulkan instance. If @c VK_NULL_HANDLE, * which is not recommended, the function will attempt * to initialize the instance-level functions via the