From 527fc2b9798a8b401d5e069afc26e63d11337f6a Mon Sep 17 00:00:00 2001
From: Max Korbel <max.korbel@intel.com>
Date: Mon, 26 Feb 2024 13:30:06 -0800
Subject: [PATCH] Fix documentation generation (#56)

---
 .github/workflows/general.yml             |  2 +-
 tool/gh_actions/check_documentation.sh    | 29 -----------------------
 tool/gh_actions/generate_documentation.sh | 23 ++++++++++++------
 tool/run_checks.sh                        |  2 +-
 4 files changed, 18 insertions(+), 38 deletions(-)
 delete mode 100755 tool/gh_actions/check_documentation.sh

diff --git a/.github/workflows/general.yml b/.github/workflows/general.yml
index c742675..e196908 100644
--- a/.github/workflows/general.yml
+++ b/.github/workflows/general.yml
@@ -44,7 +44,7 @@ jobs:
         run: tool/gh_actions/analyze_source.sh
 
       - name: Check project documentation
-        run: tool/gh_actions/check_documentation.sh
+        run: tool/gh_actions/generate_documentation.sh
 
       - name: Run project tests
         run: tool/gh_actions/run_tests.sh
diff --git a/tool/gh_actions/check_documentation.sh b/tool/gh_actions/check_documentation.sh
deleted file mode 100755
index 577bbef..0000000
--- a/tool/gh_actions/check_documentation.sh
+++ /dev/null
@@ -1,29 +0,0 @@
-#!/bin/bash
-
-# Copyright (C) 2022-2023 Intel Corporation
-# SPDX-License-Identifier: BSD-3-Clause
-#
-# check_documentation.sh
-# GitHub Actions step: Check project documentation.
-#
-# 2022 October 9
-# Author: Chykon
-
-set -euo pipefail
-
-# Output parsing is required because "dart doc" is not capable of
-# signaling a warning with an exit code:
-#   https://github.com/dart-lang/dartdoc/issues/2846
-#   https://github.com/dart-lang/dartdoc/issues/2907
-#   https://github.com/dart-lang/dartdoc/issues/1959
-
-output=$(dart doc --validate-links 2>&1 | tee)
-
-# In case of problems, the searched substring will not be found.
-if echo "${output}" | grep --silent -e 'no issues found' -e 'Success!'; then
-  echo 'Documentation check passed!'
-else
-  echo "${output}"
-  echo 'Documentation failed since some issues were found'
-  exit 1
-fi
diff --git a/tool/gh_actions/generate_documentation.sh b/tool/gh_actions/generate_documentation.sh
index 9cecffa..3fee321 100755
--- a/tool/gh_actions/generate_documentation.sh
+++ b/tool/gh_actions/generate_documentation.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Copyright (C) 2022-2023 Intel Corporation
+# Copyright (C) 2022-2024 Intel Corporation
 # SPDX-License-Identifier: BSD-3-Clause
 #
 # generate_documentation.sh
@@ -11,12 +11,21 @@
 
 set -euo pipefail
 
-# See script "check_documentation.sh" for a note on processing "dart doc" output.
+# Output parsing is required because "dart doc" is not capable of
+# signaling a warning with an exit code:
+#   https://github.com/dart-lang/dartdoc/issues/2846
+#   https://github.com/dart-lang/dartdoc/issues/2907
+#   https://github.com/dart-lang/dartdoc/issues/1959
 
-# The documentation will be placed in the "doc/api" folder.
-output=$(dart doc --validate-links 2>&1 | tee)
-
-echo "${output}"
+# Disabling --validate-links due to https://github.com/dart-lang/dartdoc/issues/3584
+# output=$(dart doc --validate-links 2>&1 | tee)
+output=$(dart doc 2>&1 | tee)
 
 # In case of problems, the searched substring will not be found.
-echo "${output}" | grep --silent 'no issues found'
+if echo "${output}" | grep --silent -e 'no issues found' -e 'Success!'; then
+  echo 'Documentation check passed!'
+else
+  echo "${output}"
+  echo 'Documentation failed since some issues were found'
+  exit 1
+fi
diff --git a/tool/run_checks.sh b/tool/run_checks.sh
index b682d76..9c449ec 100755
--- a/tool/run_checks.sh
+++ b/tool/run_checks.sh
@@ -44,7 +44,7 @@ tool/gh_actions/analyze_source.sh
 
 # Check project documentation
 print_step 'Check project documentation'
-tool/gh_actions/check_documentation.sh
+tool/gh_actions/generate_documentation.sh
 
 # Run project tests
 print_step 'Run project tests'