Catch certain documentation issues

Author: alan-george-lk

.github/workflows/generate-docs.yml

@@ -19,7 +19,7 @@ on:
       - examples/**
       - docs/**
       - README.md
-      - scripts/build-docs.sh
+      - scripts/generate-docs.sh
       - .github/workflows/generate-docs.yml
       - .github/workflows/publish-docs.yml
   workflow_call:
@@ -62,7 +62,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           # fetch-depth: 0 is required so `git describe --tags` in
-          # scripts/build-docs.sh resolves the right version from the git history.
+          # scripts/generate-docs.sh resolves the right version from the git history.
           fetch-depth: 0
 
       # Doxygen is available on ubuntu-latest, but we install explicitly for stability
@@ -86,7 +86,7 @@ jobs:
             args+=(--version "${{ github.ref_name }}")
           fi
 
-          ./scripts/build-docs.sh "${args[@]}"
+          ./scripts/generate-docs.sh "${args[@]}"
 
       - name: Print docs version
         shell: bash
@@ -104,7 +104,9 @@ jobs:
 
           {
             echo "Version: \`${PROJECT_NUMBER}\`"
-            echo "Note: On a non-tag PR, the version will resolve to \`<closest tag>-<commits since tag>-g<commit sha>\`"
+            echo ""
+            echo "> Note: On a non-tag/release run, the version will resolve to:"
+            echo "  \`<closest tag>-<commits since tag>-g<commit sha>\`"
           } >>"$GITHUB_STEP_SUMMARY"
 
       - name: Verify docs were generated

docs/Doxyfile

@@ -906,7 +906,7 @@ WARNINGS               = YES
 # will automatically be disabled.
 # The default value is: YES.
 
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 
 # If the WARN_IF_DOC_ERROR tag is set to YES, Doxygen will generate warnings for
 # potential errors in the documentation, such as documenting some parameters in
@@ -963,7 +963,7 @@ WARN_LAYOUT_FILE       = YES
 # Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT.
 # The default value is: NO.
 
-WARN_AS_ERROR          = NO
+WARN_AS_ERROR          = FAIL_ON_WARNINGS
 
 # The WARN_FORMAT tag determines the format of the warning messages that Doxygen
 # can produce. The string should contain the $file, $line, and $text tags, which
@@ -2932,15 +2932,6 @@ DOT_GRAPH_MAX_NODES    = 50
 
 MAX_DOT_GRAPH_DEPTH    = 0
 
-# Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output
-# files in one run (i.e. multiple -o and -T options on the command line). This
-# makes dot run faster, but since only newer versions of dot (>1.8.10) support
-# this, this feature is disabled by default.
-# The default value is: NO.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_MULTI_TARGETS      = NO
-
 # If the GENERATE_LEGEND tag is set to YES Doxygen will generate a legend page
 # explaining the meaning of the various boxes and arrows in the dot generated
 # graphs.

include/livekit/subscription_thread_dispatcher.h

@@ -208,6 +208,7 @@ class LIVEKIT_API SubscriptionThreadDispatcher {
   ///
   /// @param participant_identity Identity of the remote participant.
   /// @param source               Track source associated with the subscription.
+  /// @param track_name           Track name associated with the subscription.
   /// @param track                Subscribed remote track to read from.
   void handleTrackSubscribed(const std::string& participant_identity, TrackSource source, const std::string& track_name,
                              const std::shared_ptr<Track>& track);

scripts/build-docs.sh scripts/generate-docs.shscripts/build-docs.sh renamed to scripts/generate-docs.sh

@@ -21,7 +21,7 @@ repo_root="$(cd "${script_dir}/.." && pwd -P)"
 
 usage() {
   cat <<'EOF'
-Usage: ./scripts/build-docs.sh [--version VERSION]
+Usage: ./scripts/generate-docs.sh [--version VERSION]
 
 Build Doxygen HTML docs with a visible project version.
 
@@ -104,6 +104,16 @@ fi
 
 echo "==> Building Doxygen docs with PROJECT_NUMBER=${project_number}"
 cd "$repo_root"
+
+# Doxygen owns the failure decision: docs/Doxyfile sets
+#   WARN_IF_UNDOCUMENTED = NO        (silences the ~400 "X is not documented"
+#                                     warnings about internal/private symbols)
+#   WARN_AS_ERROR        = FAIL_ON_WARNINGS
+# so any remaining warning (broken @ref, unknown @-command, unsupported HTML
+# tag, malformed table, unreadable INPUT entry, etc.) fails this script via a
+# non-zero exit. There is no per-warning toggle in Doxygen; if a category
+# becomes too noisy to enforce, mute it at the WARN_IF_* level in the Doxyfile
+# rather than adding pattern allowlists here.
 LIVEKIT_DOXYGEN_PROJECT_NUMBER="$project_number" doxygen docs/Doxyfile
 
 docs_index="${repo_root}/html/index.html"