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

@@ -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 )

include/ktx.h

@@ -519,15 +519,15 @@ 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)
 
 /**
  * @~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,23 +538,23 @@ 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)
 
 /**
  * @~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)
 
 /**
  * @~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,31 +563,31 @@ 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)
 
 /**
  * @~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)
 
 /**
  * @~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)
 
 /**
  * @~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,23 +617,23 @@ 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)
 
 /**
  * @~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)
 
 /**
  * @~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)

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 <ktx.h>
@@ -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

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.
  *

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