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

@@ -0,0 +1 @@
+*.sh text eol=lf

.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
 

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.

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

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