Fix issues newly flagged by Doxygen 1.11.0 (#925)

Some were genuine issues that surprisingly weren't flagged before:
`astc_encode.cpp`, `ktx2check.c`.

One is a change to an existing Doxygen issue that caused a
previously working reference to not be found: `vkloader.c`.

Includes these other documentation related changes:

1. Change several ktxTexture references in ktxTexture2 to ktxTexture2
    references.
2. Update CI to install `graphviz` of which `dot` is part. With `dot`
    Doxygen provides nice include dependency, inverse include dependency,
    inheritance and other graphs.
3. Make Doxygen skip the documentation for the ktxTexture macro as the
    existence of a same-named macro causes Doxygen to fail to make
    intra-class cross-references in the ktxTexture class.
4. Fine tune the deprecation statements.
5. Remove names from `@file` commands. These are unnecessary and
    error-prone. Three mismatches were spotted during this work.

**IMPORTANT** Documentation for releases must not be generated with
Doxygen 1.11.0 as it has a bug that causes it to not add snippets to
generated pages. See doxygen/doxygen#10957.

Author: MarkCallow

.github/workflows/windows.yml

@@ -154,33 +154,41 @@ jobs:
       if: github.ref_type == 'tag' && matrix.check_mkvk != 'ONLY'
       run: git fetch -f origin ${{ github.ref }}:${{ github.ref }}
 
-    # Need doxygen if docs are supposed to be built.
-    # Note this suffers frequent failures due to Chocolatey attempts
+    # Need doxygen and graphviz if docs are supposed to be built.
+    # Note these suffer frequent failures due to Chocolatey attempts
     # to blackmail you into purchasing a license. Hence we retry a
     # few times. If this still fails, re-run the build.
-    - name: Install Doxygen
+    - name: Install Doxygen and Graphviz
       if: matrix.options.doc == 'ON'
       #run: choco install doxygen.install
+      #run: choco install graphviz
       run: |
-        $retryCount = 4
-        $success = $false
-        for ($i = 1; $i -le $retryCount; $i++) {
-            Write-Host "Attempt no: $i"
-            choco install doxygen.install --no-progress
-            if ($LASTEXITCODE -eq 0) {
-                $success = $true
-                Write-Host "Installation successful."
-                break
-            } else {
-                Write-Host "Installation failed. Retrying..."
-                Start-Sleep -Seconds (2*$i)
+        function Install-WithChoco {
+            param ( $Package )
+            $retryCount = 4
+            $success = $false
+            for ($i = 1; $i -le $retryCount; $i++) {
+                Write-Host "Attempt no $i for $Package"
+                # Without | Out-Host the choco output becomes output of this
+                # function because it is called from within `if`.
+                choco install $Package --no-progress --yes | Out-Host
+                if ($LASTEXITCODE -eq 0) {
+                    $success = $true
+                    Write-Host "$Package installation successful."
+                    break
+                } else {
+                    Write-Host "$Package installation failed. Retrying..."
+                    Start-Sleep -Seconds (2*$i)
+                }
+            }
+            if (-not $success) {
+                Write-Host "$Package installation failed after $retryCount attempts."
             }
+            return $success
         }
-        if (-not $success) {
-            Write-Host "Installation failed after $retryCount attempts."
+        if (-not ((Install-WithChoco doxygen.install) -and (Install-WithChoco graphviz))) {
             exit 1
         }
-
     - name: Install AzureSignTool
       if: matrix.check_mkvk != 'ONLY'
       id: install-ast

.travis.yml

@@ -20,7 +20,6 @@ addons:
     update: false
     packages:
     - git-lfs
-    - doxygen
 
 env:
   global:
@@ -107,6 +106,7 @@ jobs:
       addons:
         apt:
           packages:
+            - graphviz
             - python3
             - python3-venv
       compiler: gcc
@@ -127,6 +127,7 @@ jobs:
       addons:
         apt:
           packages:
+            - graphviz
             - python3
             - python3-venv
       compiler: gcc
@@ -246,6 +247,10 @@ install:
           brew install sdl2
           brew install assimp
       fi
+      if [ "$FEATURE_DOC" = "ON" ]; then
+          brew install doxygen
+          brew install graphviz
+      fi
       ./scripts/install_macos.sh
     fi
     ;;

BUILDING.md

@@ -570,13 +570,23 @@ For iOS and macOS, install the Vulkan SDK by downloading the macOS installer and
 
 ### Doxygen
 
-Needed if you want to generate the _libktx_ and _ktxtools_ documentation.
+Needed if you want to generate _libktx_, _ktxtools_ and other documentation.
 
-You need a minimum of version 1.8.14 to generate the documentation correctly. You
-can download binaries and also find instructions for building it from source at
-[Doxygen downloads](http://www.stack.nl/~dimitri/doxygen/download.html). Make
+You need a minimum of version 1.8.14 to generate the documentation correctly.
+You can download binaries and also find instructions for building it from source
+at [Doxygen downloads](http://www.stack.nl/~dimitri/doxygen/download.html). Make
 sure the directory containing the `doxygen` executable is in your `$PATH`.
 
+### dot (Graphviz)
+
+Needed if you want Doxygen to generate include dependency, inverse include
+dependency, inheritance and other graphs in the generated documentation.
+
+You can download binaries from
+[Graphviz downloads](https://graphviz.org/download/).
+
+Optional. If not present documentation will be generated minus graphs. 
+
 ### libassimp
 
 Needed if you want to build the KTX load tests.

cmake/docs.cmake

@@ -1,7 +1,15 @@
 # Copyright 2015-2020 The Khronos Group Inc.
 # SPDX-License-Identifier: Apache-2.0
 
-find_package(Doxygen REQUIRED)
+# dot is optional as missing include dependency graphs and
+# inheritance graphs is not a big enough deal to justify
+# forcing people to install Graphviz.
+find_package(Doxygen REQUIRED OPTIONAL_COMPONENTS dot)
+if(NOT DOXYGEN_DOT_EXECUTABLE)
+    message(NOTICE "dot executable not found so Doxygen will not generate\n"
+                   "include dependency or inheritance graphs in the documentation.\n"
+                   "If you want these graphs, install Graphviz.")
+endif()
 
 set(docdest "${CMAKE_CURRENT_BINARY_DIR}/docs")
 
@@ -85,6 +93,7 @@ function( CreateDocLibKTX )
     set( DOXYGEN_EXPAND_ONLY_PREDEF YES )
 
     set( DOXYGEN_PREDEFINED
+    KTX_DOXYGEN_SKIP
     "KTXTEXTURECLASSDEFN=class_id classId\; \\
         struct ktxTexture_vtbl* vtbl\;             \\
         struct ktxTexture_vvtbl* vvtbl\;           \\

include/KHR/khr_df.h

@@ -17,10 +17,10 @@
 #ifndef _KHR_DATA_FORMAT_H_
 #define _KHR_DATA_FORMAT_H_
 
-/** @file khr_df.h
-
-    @brief Data Format enums and macros.
-*/
+/** @file
+ * @~English
+ * @brief Data Format enums and macros.
+ */
 
 /* Accessors */
 typedef enum _khr_word_e {

include/ktx.h

@@ -191,8 +191,8 @@ typedef enum ktx_error_code_e {
     KTX_ERROR_MAX_ENUM = KTX_DECOMPRESS_CHECKSUM_ERROR /*!< For safety checks. */
 } ktx_error_code_e;
 /**
- * @deprecated
  * @~English
+ * @deprecated Use #ktx_error_code_e.
  * @brief For backward compatibility
  */
 #define KTX_error_code ktx_error_code_e
@@ -719,12 +719,24 @@ typedef struct ktxTexture2 {
     struct ktxTexture2_private* _private;  /*!< Private data. */
 } ktxTexture2;
 
-/**
- * @brief Helper for casting ktxTexture1 and ktxTexture2 to ktxTexture.
+/*
+ * If Doxygen sees this macro it gets confused and fails to spot
+ * references to ktxTexture_*() functions in the running text. It
+ * also complains it can't find the reference when @ref is used
+ * with a fully qualified method name to make an intra-class
+ * reference in the @c ktxTexture class.
+ * See https://github.com/doxygen/doxygen/issues/10311.
  *
- * Use with caution.
- */
-#define ktxTexture(t) ((ktxTexture*)t)
+ * Not documenting the macro is the lesser of two evils.
+ */
+#if !defined(KTX_DOXYGEN_SKIP)
+    /**
+     * @brief Helper for casting ktxTexture1 and ktxTexture2 to ktxTexture.
+     *
+     * Use with caution.
+     */
+    #define ktxTexture(t) ((ktxTexture*)t)
+#endif
 
 /**
  * @memberof ktxTexture
@@ -1391,7 +1403,7 @@ typedef struct ktxBasisParams {
              Only valid for linear textures.
          */
     ktx_bool_t separateRGToRGB_A;
-        /*!< @deprecated. This was and is a no-op. 2-component inputs have
+        /*!< @deprecated This was and is a no-op. 2-component inputs have
             always been automatically separated using an "rrrg" inputSwizzle.
             @sa inputSwizzle and normalMode.
          */
@@ -1586,25 +1598,25 @@ typedef enum ktx_transcode_fmt_e {
         // Old enums for compatibility with code compiled against previous
         // versions of libktx.
         KTX_TF_ETC1 = KTX_TTF_ETC1_RGB,
-            //!< @deprecated. Use #KTX_TTF_ETC1_RGB.
+            //!< @deprecated Use #KTX_TTF_ETC1_RGB.
         KTX_TF_ETC2 = KTX_TTF_ETC,
-            //!< @deprecated. Use #KTX_TTF_ETC.
+            //!< @deprecated Use #KTX_TTF_ETC.
         KTX_TF_BC1 = KTX_TTF_BC1_RGB,
-            //!< @deprecated. Use #KTX_TTF_BC1_RGB.
+            //!< @deprecated Use #KTX_TTF_BC1_RGB.
         KTX_TF_BC3 = KTX_TTF_BC3_RGBA,
-            //!< @deprecated. Use #KTX_TTF_BC3_RGBA.
+            //!< @deprecated Use #KTX_TTF_BC3_RGBA.
         KTX_TF_BC4 = KTX_TTF_BC4_R,
-            //!< @deprecated. Use #KTX_TTF_BC4_R.
+            //!< @deprecated Use #KTX_TTF_BC4_R.
         KTX_TF_BC5 = KTX_TTF_BC5_RG,
-            //!< @deprecated. Use #KTX_TTF_BC5_RG.
+            //!< @deprecated Use #KTX_TTF_BC5_RG.
         KTX_TTF_BC7_M6_RGB = KTX_TTF_BC7_RGBA,
-            //!< @deprecated. Use #KTX_TTF_BC7_RGBA.
+            //!< @deprecated Use #KTX_TTF_BC7_RGBA.
         KTX_TTF_BC7_M5_RGBA = KTX_TTF_BC7_RGBA,
-            //!< @deprecated. Use #KTX_TTF_BC7_RGBA.
+            //!< @deprecated Use #KTX_TTF_BC7_RGBA.
         KTX_TF_BC7_M6_OPAQUE_ONLY = KTX_TTF_BC7_RGBA,
-            //!< @deprecated. Use #KTX_TTF_BC7_RGBA
+            //!< @deprecated Use #KTX_TTF_BC7_RGBA
         KTX_TF_PVRTC1_4_OPAQUE_ONLY = KTX_TTF_PVRTC1_4_RGB
-            //!< @deprecated. Use #KTX_TTF_PVRTC1_4_RGB.
+            //!< @deprecated Use #KTX_TTF_PVRTC1_4_RGB.
 } ktx_transcode_fmt_e;
 
 /**

lib/astc_encode.cpp

@@ -8,7 +8,7 @@
 
 /**
  * @internal
- * @file astc_encode.cpp
+ * @file
  * @~English
  *
  * @brief Functions for compressing a texture to ASTC format.
@@ -201,7 +201,7 @@ unorm8x4ArrayToImage(const uint8_t *data, uint32_t dim_x, uint32_t dim_y) {
 
 /**
  * @memberof ktxTexture
- * @ingroup write
+ * @ingroup writer
  * @~English
  * @brief       Creates default ASTC parameters
  *
@@ -222,7 +222,7 @@ astcDefaultOptions() {
 
 /**
  * @memberof ktxTexture
- * @ingroup write
+ * @ingroup writer
  * @~English
  * @brief       Should be used to get VkFormat from ASTC block enum
  *
@@ -291,7 +291,7 @@ astcVkFormat(ktx_uint32_t block_size, bool sRGB) {
 
 /**
  * @memberof ktxTexture
- * @ingroup write
+ * @ingroup writer
  * @~English
  * @brief Creates valid ASTC encoder action from string.
  *
@@ -320,7 +320,7 @@ astcEncoderAction(const ktxAstcParams &params, const uint32_t* bdb) {
 
 /**
  * @memberof ktxTexture
- * @ingroup write
+ * @ingroup writer
  * @~English
  * @brief Creates valid ASTC encoder swizzle from string.
  *

lib/basis_encode.cpp

@@ -8,7 +8,7 @@
 
 /**
  * @internal
- * @file basis_encode.cpp
+ * @file
  * @~English
  *
  * @brief Functions for supercompressing a texture with Basis Universal.

lib/basis_transcode.cpp

@@ -8,7 +8,7 @@
 
 /**
  * @internal
- * @file basis_transcode.cpp
+ * @file
  * @~English
  *
  * @brief Functions for transcoding Basis Universal BasisLZ/ETC1S and UASTC textures.

lib/checkheader.c

@@ -10,7 +10,7 @@
 
 /**
  * @internal
- * @file checkheader.c
+ * @file
  * @~English
  *
  * @brief Function to verify a KTX file header