From fd0fd8795125d9e485c79472ee8582e78b3df4d9 Mon Sep 17 00:00:00 2001
From: ladyada <ladyada@rogflow>
Date: Tue, 15 Sep 2026 17:01:10 -0400
Subject: [PATCH] Check documentation with the CI Doxygen version

Document the deleted assignment return and add a local check using the
same Doxygen 1.8.13 binary, configuration, and warning policy as CI.
Run it before regression tests to expose documentation failures early.

Co-authored-by: Limor Fried <ladyada@users.noreply.github.com>
---
 .gitattributes                 |  1 +
 .github/workflows/githubci.yml |  2 ++
 extras/tests/README.md         | 13 ++++++++++
 extras/tests/check_doxygen.sh  | 43 ++++++++++++++++++++++++++++++++++
 src/Adafruit_NMEA.h            |  1 +
 5 files changed, 60 insertions(+)
 create mode 100644 .gitattributes
 create mode 100644 extras/tests/check_doxygen.sh

diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..dfdb8b7
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1 @@
+*.sh text eol=lf
diff --git a/.github/workflows/githubci.yml b/.github/workflows/githubci.yml
index 8c2081f..33582c5 100644
--- a/.github/workflows/githubci.yml
+++ b/.github/workflows/githubci.yml
@@ -9,6 +9,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
+    - name: Check Doxygen before tests
+      run: bash extras/tests/check_doxygen.sh
     - name: Run all tests with sanitizers
       run: python3 extras/tests/run_tests.py
 
diff --git a/extras/tests/README.md b/extras/tests/README.md
index d905ad4..e64d922 100644
--- a/extras/tests/README.md
+++ b/extras/tests/README.md
@@ -22,3 +22,16 @@ output and a real monotonic clock; the wakeup timeout test takes ten seconds.
 I2C, SPI, GPIO, and hardware serial input abort if used. This runs the parser
 and mock-stream regressions, not physical GPS/SD hardware or MCU emulation.
 The sketches remain usable on Arduino boards with the normal Arduino core.
+
+Check documentation before pushing, on Linux or Windows through WSL:
+
+```sh
+bash extras/tests/check_doxygen.sh
+```
+
+This requires `curl` and `tar` and downloads the same Doxygen 1.8.13 binary and
+default configuration used by Adafruit's documentation deployment job. Any
+Doxygen output or missing HTML fails the check; a newer system Doxygen is not
+a substitute. Build files and the diagnostic log stay in a temporary directory
+outside the checkout. CI runs this check before the regression tests, so
+documentation failures appear without waiting for all Arduino builds.
diff --git a/extras/tests/check_doxygen.sh b/extras/tests/check_doxygen.sh
new file mode 100644
index 0000000..40b1e0c
--- /dev/null
+++ b/extras/tests/check_doxygen.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Match ci-arduino's documentation check without cloning or publishing gh-pages.
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+build="$(mktemp -d "${TMPDIR:-/tmp}/gps-doxygen.XXXXXX")"
+echo "Doxygen check output: $build"
+
+# ci/doxy_gen_and_deploy.sh uses this binary, not the system Doxygen version.
+curl --fail --location --silent --show-error --connect-timeout 15 --max-time 120 \
+  https://cdn-learn.adafruit.com/assets/assets/000/067/405/original/doxygen-1.8.13.linux.bin.tar.gz \
+  --output "$build/doxygen.tar.gz"
+tar -xzf "$build/doxygen.tar.gz" -C "$build" doxygen-1.8.13/bin/doxygen
+
+if [[ -f "$root/Doxyfile" ]]; then
+  cp "$root/Doxyfile" "$build/Doxyfile"
+else
+  curl --fail --location --silent --show-error --connect-timeout 15 --max-time 120 \
+    https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/Doxyfile.default \
+    --output "$build/Doxyfile"
+fi
+cat >> "$build/Doxyfile" <<EOF
+
+PROJECT_NAME = "Adafruit GPS Library"
+HTML_OUTPUT = "$build/html"
+INPUT = "$root/src"
+EOF
+
+cd "$root"
+if ! "$build/doxygen-1.8.13/bin/doxygen" "$build/Doxyfile" > "$build/doxygen.log" 2>&1; then
+  cat "$build/doxygen.log" >&2
+  exit 1
+fi
+# The deployment job rejects any output, even when Doxygen exits successfully.
+if [[ -s "$build/doxygen.log" ]]; then
+  cat "$build/doxygen.log" >&2
+  exit 1
+fi
+if [[ ! -s "$build/html/index.html" ]]; then
+  echo "Doxygen did not generate html/index.html" >&2
+  exit 1
+fi
+echo "Doxygen 1.8.13 passed with no warnings."
diff --git a/src/Adafruit_NMEA.h b/src/Adafruit_NMEA.h
index 2fc471b..f38fa7c 100644
--- a/src/Adafruit_NMEA.h
+++ b/src/Adafruit_NMEA.h
@@ -75,6 +75,7 @@ public:
   Adafruit_NMEA(const Adafruit_NMEA &other) = delete;
   /// @brief Assignment is disabled to prevent sharing writable receive buffers.
   /// @param other Receiver that cannot be assigned.
+  /// @return No value; this deleted operation cannot be called.
   Adafruit_NMEA &operator=(const Adafruit_NMEA &other) = delete;
   void reset();
   nmea_frame_status_t feed(uint8_t byte, uint32_t receivedAtMs);