TASK-043: Doxygen / inline doc refresh

Refresh public-header doxygen blocks to match the v2.0 surface, and
add a make-check gate (check-doxygen.sh) that fails on any substantive
doxygen warning. The gate is wired into check-local via Makefile.am
following the precedent established by TASK-040/041/042.

Substantive doxygen-source warnings fixed (17 → 0):

* `webserver.hpp` register_path/register_prefix/register_ws_resource:
  the shared_ptr overloads used `@copydoc <template-overload>` followed
  by an `@param res` override, which doxygen flags as "too many @param".
  Replace the @copydoc with a fresh self-contained block on each
  overload (same prose, no duplicate @param).
* `http_request.hpp` check_digest_auth / check_digest_auth_digest:
  add explicit @param blocks for realm/password/nonce_timeout/max_nc/algo
  on check_digest_auth, and replace the @copydoc-based block on
  check_digest_auth_digest with a self-contained one (copydoc was
  inheriting `password` which is not in the digest variant's signature).
* `http_request.hpp` get_or_create_file_info: add missing `@param key`.
* `http_resource.hpp` render: name the previously-anonymous `req`
  parameter so the `@param req` in the doc block resolves.
* `http_utils.hpp` get_ip_str: drop the stale `@param maxlen` block left
  over from the v1 two-arg signature.
* `http_utils.hpp` header_comparator::operator() and arg_comparator::
  operator(): rename `@param first/second` to match the actual `x, y`
  signature, and document the case-sensitivity contract on the arg
  variant.

Acceptance-criterion content (per the task action items):

* AC bullet 3 — threading: add a `### Threading contract (DR-008 / §5.1)`
  block on the `webserver` class summarising the 5-point contract
  (re-entrant registration; stop/destructor must not run on a handler
  thread; per-request http_request; exclusive http_response; concurrent
  user callbacks).
* AC bullet 4 — error propagation: add a load-bearing block on
  `create_webserver::internal_error_handler` that spells out the DR-009
  §5.2 6-point contract verbatim, cross-linking to @ref webserver,
  not_found_handler, method_not_allowed_handler, feature_unavailable.
  Also document `internal_error_handler_t` (the typedef) explaining
  the std::string_view ownership rules.
* AC bullet 5 — feature_unavailable throw sites: enumerate the throw
  sites on the feature_unavailable class itself (webserver ctor for
  TLS/BAUTH/DAUTH, register_ws_resource / unregister_ws_resource for
  HAVE_WEBSOCKET, and every send_* / close on websocket_session).
* AC bullet 2 — cross-links: `@see` pairs added between block_ip ↔
  unblock_ip, register_path ↔ register_prefix, the unregister_*
  family, register_ws_resource ↔ unregister_ws_resource, and the
  three error-handler setters.
* Class-level docs added on `create_webserver` (fluent-builder
  contract, eager validation, explicit webserver ctor), and on
  `websocket_session` / `websocket_handler` (per-method param/return/
  throws blocks including the HAVE_WEBSOCKET-off feature_unavailable
  behaviour).

Verification:

* `make check` green (48 testsuite entries pass; check-headers,
  check-examples, check-readme, check-release-notes, check-doxygen,
  check-install-layout, check-hygiene all PASS).
* `make doxygen-run` now produces zero substantive warnings; the
  remaining stderr lines (obsolete config tags, dot/graphviz env
  artifacts when graphviz is missing) are explicitly filtered by
  scripts/check-doxygen.sh.
* Spot-check on 11 v2.0-renamed/reshaped public methods
  (register_path, register_prefix, internal_error_handler, block_ip,
  unblock_ip, route, on_get, use_ssl, basic_auth, register_ws_resource,
  feature_unavailable) — each has a current `///` or `/**` block with
  @param/@return/@see reflecting the v2.0 signature.

The gate skips with exit 0 when doxygen is not installed (mirrors the
tolerance pattern used by the other check-* scripts); in CI the gate
runs whenever the doxygen package is present.

PRD §2 documentation NFR; §13 documentation deliverable.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: etr

Makefile.am

@@ -40,6 +40,7 @@ endif
 
 EXTRA_DIST = libhttpserver.pc.in $(DX_CONFIG) scripts/extract-release-notes.sh scripts/validate-version.sh \
 	scripts/check-examples.sh scripts/check-readme.sh scripts/check-release-notes.sh \
+	scripts/check-doxygen.sh \
 	scripts/verify-installed-examples.sh \
 	test/headers/consumer_direct.cpp test/headers/consumer_detail.cpp test/headers/consumer_umbrella.cpp \
 	test/headers/consumer_post_umbrella.cpp \
@@ -283,7 +284,7 @@ check-hygiene:
 # shared staged install to avoid paying two full `make install` costs on
 # every `make check`. Both sub-checks can still be invoked standalone (they
 # will do their own install when CHECK_*_SHARED is not set).
-check-local: check-headers check-examples check-readme check-release-notes
+check-local: check-headers check-examples check-readme check-release-notes check-doxygen
 	@echo "=== Shared staged install for check-install-layout and check-hygiene ==="
 	@rm -rf $(abs_top_builddir)/.shared-check-stage
 	@$(MAKE) $(AM_MAKEFLAGS) install DESTDIR=$(abs_top_builddir)/.shared-check-stage >check-shared-install.log 2>&1 || { \
@@ -319,7 +320,15 @@ check-release-notes:
 	@echo "=== check-release-notes: enforce TASK-042 invariants on RELEASE_NOTES.md ==="
 	@$(top_srcdir)/scripts/check-release-notes.sh
 
-.PHONY: check-headers check-install-layout check-hygiene check-examples check-readme check-release-notes
+# TASK-043: run doxygen and fail on any substantive warning. The script
+# delegates to `make doxygen-run` and parses stderr; environmental noise
+# (obsolete config tags, missing graphviz) is filtered out. Skips with
+# exit 0 if doxygen is not installed.
+check-doxygen:
+	@echo "=== check-doxygen: enforce TASK-043 zero-warning invariant ==="
+	@BUILD_DIR="$(abs_top_builddir)" $(top_srcdir)/scripts/check-doxygen.sh
+
+.PHONY: check-headers check-install-layout check-hygiene check-examples check-readme check-release-notes check-doxygen
 
 # TASK-039: top-level convenience rule that descends into test/ to
 # build and run the bench binaries (see test/Makefile.am and

scripts/check-doxygen.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+#
+# check-doxygen.sh — enforce TASK-043 invariant on the doxygen build.
+#
+# Runs `make doxygen-run` in the active build tree and asserts that the
+# output contains zero substantive warnings or errors. Substantive means:
+# anything from the doxygen parser about the SOURCE under
+# `src/httpserver/` — e.g. an undocumented @param, a mismatched parameter
+# name, a stale @copydoc target.
+#
+# Lines we deliberately filter OUT (environmental, not doc-content issues):
+#
+#   E1. "Tag '<NAME>' at line N of file '...doxyconfig.in' has become
+#       obsolete." — older config tags carried over from doxywizard.
+#   E2. "doxygen no longer ships with the FreeSans font." — packaging.
+#   E3. "the dot tool could not be found ..." — graphviz absent locally.
+#   E4. "Failed to rename ... .dot.png to ... .png" — dot post-processing
+#       failure (typically dot absent or installed late).
+#   E5. "Problems running dot: exit code=..." — same root cause as E4.
+#   E6. "Caller graph for '<sym>' not generated, too many nodes (N),
+#       threshold is M." — informational, DOT_GRAPH_MAX_NODES threshold.
+#
+# Everything else under the keywords `warning:` or `error:` is a real
+# doc issue and FAILS the gate. Exits non-zero on the first violation.
+#
+# Behaviour when doxygen is not installed: SKIP (exit 0). The gate is
+# CI-runnable on developer machines without doxygen; CI is expected to
+# install it. This mirrors how scripts/check-readme.sh and friends are
+# tolerant of missing tools.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# Locate the build tree. Prefer $BUILD_DIR, else REPO_ROOT/build, else
+# fall back to the current working directory (assumes invoker is already
+# inside the build dir, mirroring `make` behaviour).
+BUILD_DIR="${BUILD_DIR:-}"
+if [ -z "$BUILD_DIR" ]; then
+    if [ -d "$REPO_ROOT/build" ] && [ -f "$REPO_ROOT/build/Makefile" ]; then
+        BUILD_DIR="$REPO_ROOT/build"
+    elif [ -f "Makefile" ]; then
+        BUILD_DIR="$(pwd)"
+    else
+        echo "check-doxygen: FAIL: no build directory found (set BUILD_DIR)" >&2
+        exit 1
+    fi
+fi
+
+if ! command -v doxygen >/dev/null 2>&1; then
+    echo "check-doxygen: SKIP — doxygen not installed (gate is enforced in CI)"
+    exit 0
+fi
+
+LOGFILE="$(mktemp -t check-doxygen.XXXXXX)"
+trap 'rm -f "$LOGFILE"' EXIT
+
+echo "check-doxygen: invoking 'make doxygen-run' in $BUILD_DIR"
+# Force a fresh doxygen invocation. The make rule's recipe already does
+# `rm -rf doxygen-doc` but only fires when an input is newer than the
+# tag file. When NO header has changed (e.g. CI rerun) doxygen does not
+# re-execute and warnings from a prior good run would not reappear here.
+# Removing the tag file forces the rule to fire every time.
+rm -f "$BUILD_DIR/doxygen-doc/libhttpserver.tag"
+if ! ( cd "$BUILD_DIR" && make doxygen-run ) >"$LOGFILE" 2>&1; then
+    echo "check-doxygen: FAIL: 'make doxygen-run' exited non-zero" >&2
+    sed -n '1,200p' "$LOGFILE" >&2
+    exit 1
+fi
+
+# Strip the noisy-but-harmless environmental lines. The grep is portable
+# (BSD/GNU): -E for ERE alternation, single anchored pattern per line.
+FILTER='Tag .* has become obsolete\.'
+FILTER+='|doxygen no longer ships with the FreeSans font'
+FILTER+='|the dot tool could not be found'
+FILTER+='|Failed to rename .*\.dot\.png to'
+FILTER+='|Problems running dot: exit code='
+FILTER+='|Caller graph for .* not generated, too many nodes'
+
+REAL_WARNINGS="$(grep -E '(^|: )(warning|error):' "$LOGFILE" | grep -Ev "$FILTER" || true)"
+
+if [ -n "$REAL_WARNINGS" ]; then
+    echo "check-doxygen: FAIL: substantive doxygen warnings/errors found:" >&2
+    echo "$REAL_WARNINGS" >&2
+    echo "" >&2
+    echo "(Full log: $LOGFILE — copy aside if needed before this script exits.)" >&2
+    # Preserve log on failure for inspection.
+    trap - EXIT
+    exit 1
+fi
+
+echo "check-doxygen: PASS — doxygen-run produced zero substantive warnings"

src/httpserver/create_webserver.hpp

@@ -46,11 +46,25 @@ namespace httpserver {
 class webserver;
 class http_request;
 
-// TASK-030 / PRD-NAM-REQ-003 — see specs/architecture/04-components/create-webserver.md.
+/**
+ * Callback signature for the 404 and 405 error-page handlers.
+ *
+ * Returned by value; the webserver writes the response to the wire.
+ * (TASK-030 / PRD-NAM-REQ-003 — see specs/architecture/04-components/create-webserver.md.)
+ */
 typedef std::function<http_response(const http_request&)> error_handler;
 
-// TASK-031 / DR-009 §5.2 — internal_error_handler receives the originating
-// exception's message as a non-owning view; see create-webserver.md.
+/**
+ * Callback signature for @ref create_webserver::internal_error_handler.
+ *
+ * The handler receives the originating exception's message as a non-owning
+ * `std::string_view` — for `std::exception` derivatives this is `e.what()`;
+ * for non-`std::exception` throws (`throw 42`) it is the literal string
+ * `"unknown exception"`. The view is valid only for the duration of the
+ * call; copy if you need to retain it.
+ *
+ * Full contract: DR-009 §5.2 (see @ref webserver class-level block).
+ */
 typedef std::function<http_response(const http_request&, std::string_view message)> internal_error_handler_t;
 
 typedef std::function<bool(const std::string&)> validator_ptr;
@@ -66,6 +80,25 @@ namespace http { class file_info; }
 typedef std::function<bool(const std::string&, const std::string&, const http::file_info&)> file_cleanup_callback_ptr;
 typedef std::function<std::shared_ptr<http_response>(const http_request&)> auth_handler_ptr;
 
+/**
+ * Fluent builder for @ref webserver instances (PRD-NAM-REQ-004,
+ * PRD-CFG-REQ-001..003 / TASK-033).
+ *
+ * Each setter returns `*this` so calls can chain:
+ * `webserver ws{create_webserver{}.port(8080).use_ssl(true).max_threads(4)};`
+ *
+ * Setters validate eagerly where the input domain is well-defined
+ * (e.g. @ref port rejects values outside `[0, 65535]`, all `int` setters
+ * reject negatives); feature-gated settings (@ref use_ssl,
+ * @ref basic_auth, @ref digest_auth, websocket registration) are
+ * validated when the @ref webserver constructor consumes the builder,
+ * not at the setter — so a builder configured for an unsupported
+ * feature throws @ref feature_unavailable from `webserver(create_webserver)`
+ * rather than from the setter.
+ *
+ * The @ref webserver constructor is `explicit`: callers must direct-init
+ * (`webserver ws{cw};`) rather than rely on implicit conversion.
+ */
 class create_webserver {
  public:
      create_webserver() = default;
@@ -102,6 +135,16 @@ class create_webserver {
      create_webserver& max_thread_stack_size(int v) { check_non_negative("max_thread_stack_size", v); _max_thread_stack_size = v; return *this; }
 
      // Boolean flag setters (TASK-033 / PRD-CFG-REQ-001).
+     /**
+      * Enable TLS for the webserver (HTTPS).
+      *
+      * On a `HAVE_GNUTLS`-off build, constructing a @ref webserver from a
+      * builder with `use_ssl(true)` throws @ref feature_unavailable.
+      * Defaults to `false`.
+      *
+      * @param enable `true` to enable TLS, `false` to disable.
+      * @return reference to this builder for chaining.
+      */
      create_webserver& use_ssl(bool enable = true) { _use_ssl = enable; return *this; }
      create_webserver& use_ipv6(bool enable = true) { _use_ipv6 = enable; return *this; }
      create_webserver& use_dual_stack(bool enable = true) { _use_dual_stack = enable; return *this; }
@@ -125,7 +168,27 @@ class create_webserver {
      // validation lives in webserver(const create_webserver&), which
      // throws feature_unavailable when this is set to true on a
      // HAVE_BAUTH-off build.
+     /**
+      * Enable HTTP Basic authentication on the webserver.
+      *
+      * On a `HAVE_BAUTH`-off build, constructing a @ref webserver from a
+      * builder with `basic_auth(true)` throws @ref feature_unavailable.
+      * Default value depends on the build flag (see TASK-034).
+      *
+      * @param enable `true` to enable Basic auth, `false` to disable.
+      * @return reference to this builder for chaining.
+      */
      create_webserver& basic_auth(bool enable = true) { _basic_auth_enabled = enable; return *this; }
+     /**
+      * Enable HTTP Digest authentication on the webserver.
+      *
+      * On a `HAVE_DAUTH`-off build, constructing a @ref webserver from a
+      * builder with `digest_auth(true)` throws @ref feature_unavailable.
+      * Default value depends on the build flag.
+      *
+      * @param enable `true` to enable Digest auth, `false` to disable.
+      * @return reference to this builder for chaining.
+      */
      create_webserver& digest_auth(bool enable = true) { _digest_auth_enabled = enable; return *this; }
      create_webserver& deferred(bool enable = true) { _deferred_enabled = enable; return *this; }
      create_webserver& regex_checking(bool enable = true) { _regex_checking = enable; return *this; }
@@ -141,8 +204,60 @@ class create_webserver {
      create_webserver& generate_random_filename_on_upload(bool enable = true) { _generate_random_filename_on_upload = enable; return *this; }
      create_webserver& single_resource(bool enable = true) { _single_resource = enable; return *this; }
      create_webserver& tcp_nodelay(bool enable = true) { _tcp_nodelay = enable; return *this; }
+     /**
+      * Install a handler invoked when no resource matches the request path (HTTP 404).
+      *
+      * The handler returns an @ref http_response by value; its status
+      * code, headers, and body are sent on the wire as-is. If null, a
+      * default 404 response is generated.
+      *
+      * @param h error_handler callback; pass `nullptr` to clear.
+      * @return reference to this builder for chaining.
+      * @see method_not_allowed_handler, internal_error_handler
+      */
      create_webserver& not_found_handler(error_handler h) { _not_found_handler = std::move(h); return *this; }
+     /**
+      * Install a handler invoked when a resource matches the path but
+      * not the HTTP method (HTTP 405).
+      *
+      * The handler returns an @ref http_response by value. If null, a
+      * default 405 response is generated.
+      *
+      * @param h error_handler callback; pass `nullptr` to clear.
+      * @return reference to this builder for chaining.
+      * @see not_found_handler, internal_error_handler
+      */
      create_webserver& method_not_allowed_handler(error_handler h) { _method_not_allowed_handler = std::move(h); return *this; }
+     /**
+      * Install the handler invoked when a registered request handler
+      * throws (HTTP 500 by default).
+      *
+      * This is the load-bearing extension point for the dispatch
+      * error-propagation contract (DR-009 §5.2 / PRD-FLG-REQ-002). The
+      * contract — full statement on the @ref webserver class block — is:
+      *
+      *   1. The handler call is wrapped in `try/catch (std::exception&) / catch (...)`.
+      *   2. On `std::exception`: the message is logged via @ref log_error,
+      *      then @p h is invoked with `e.what()` as the @ref internal_error_handler_t
+      *      `message` argument.
+      *   3. On non-`std::exception`: same path with the message replaced
+      *      by the literal string `"unknown exception"`.
+      *   4. If @p h itself throws while servicing the above, the failure
+      *      is logged generically and a hardcoded 500 with an EMPTY body
+      *      is sent. No exception ever escapes into libmicrohttpd.
+      *   5. @ref feature_unavailable (a `std::runtime_error` subclass) is
+      *      NOT mapped specially: it lands as a generic 500 like any
+      *      other `std::exception`.
+      *   6. May run concurrently from multiple MHD worker threads;
+      *      implementations MUST be thread-safe.
+      *
+      * If @p h is null, the default response is a 500 with the message
+      * in the body (see DR-009).
+      *
+      * @param h @ref internal_error_handler_t callback; pass `nullptr` to clear.
+      * @return reference to this builder for chaining.
+      * @see webserver, not_found_handler, method_not_allowed_handler, feature_unavailable
+      */
      create_webserver& internal_error_handler(internal_error_handler_t h) { _internal_error_handler = std::move(h); return *this; }
      create_webserver& file_cleanup_callback(file_cleanup_callback_ptr v) { _file_cleanup_callback = v; return *this; }
      create_webserver& auth_handler(auth_handler_ptr v) { _auth_handler = v; return *this; }

src/httpserver/feature_unavailable.hpp

@@ -31,17 +31,60 @@
 
 namespace httpserver {
 
-// Exception thrown when a build-time-disabled feature is invoked at runtime.
-// The class is unconditionally available regardless of HAVE_* flags so that
-// downstream code can always write
-//     try { ... } catch (const httpserver::feature_unavailable&) { ... }
-// even in builds that compiled out the optional feature in question.
-//
-// The class is header-only (and inline) on purpose: it has no library
-// dependencies, must be cheap to throw from anywhere in the codebase, and
-// avoids ABI churn for what is effectively a labelled std::runtime_error.
+/**
+ * Exception thrown when a build-time-disabled feature is invoked at runtime.
+ *
+ * The class is unconditionally available regardless of `HAVE_*` flags so
+ * that downstream code can always write
+ * @code
+ *     try { ... } catch (const httpserver::feature_unavailable&) { ... }
+ * @endcode
+ * even in builds that compiled out the optional feature in question.
+ *
+ * The class is header-only (and inline) on purpose: it has no library
+ * dependencies, must be cheap to throw from anywhere in the codebase, and
+ * avoids ABI churn for what is effectively a labelled `std::runtime_error`.
+ *
+ * ### Throw sites (architecture spec §7)
+ *
+ * The library throws `feature_unavailable` from these sites; each one
+ * pairs the feature label with the `HAVE_*` build flag that gates it:
+ *
+ *   - @ref webserver::webserver — when constructing from a builder that
+ *     enables `use_ssl(true)` on a `HAVE_GNUTLS`-off build, or
+ *     `basic_auth(true)` on a `HAVE_BAUTH`-off build, or
+ *     `digest_auth(true)` on a `HAVE_DAUTH`-off build.
+ *   - @ref webserver::register_ws_resource and
+ *     @ref webserver::unregister_ws_resource — on a `HAVE_WEBSOCKET`-off
+ *     build (every websocket entry point throws this).
+ *   - @ref websocket_session::send_text, @ref websocket_session::send_binary,
+ *     @ref websocket_session::send_ping, @ref websocket_session::send_pong,
+ *     and @ref websocket_session::close — on a `HAVE_WEBSOCKET`-off build,
+ *     so that downstream handlers that capture a session reference get a
+ *     uniform exception type rather than a link-time error.
+ *
+ * Catching `feature_unavailable` (or its base `std::runtime_error`) on
+ * the dispatch path is handled by the standard
+ * @ref webserver internal_error_handler contract — it surfaces as a
+ * generic 500 unless the application installs an
+ * @ref create_webserver::internal_error_handler that special-cases it.
+ *
+ * @see create_webserver::use_ssl, create_webserver::basic_auth,
+ *      create_webserver::digest_auth, webserver::register_ws_resource,
+ *      websocket_session
+ */
 class feature_unavailable : public std::runtime_error {
  public:
+    /**
+     * Construct with the feature name and the build flag that gates it.
+     *
+     * The resulting `what()` is
+     * `"feature '<feature>' unavailable: built without <build_flag>"`.
+     *
+     * @param feature    human-readable feature label (e.g. `"TLS"`, `"WebSocket"`).
+     * @param build_flag the autoconf-defined `HAVE_*` flag that was off
+     *                   in this build (e.g. `"HAVE_GNUTLS"`).
+     */
     feature_unavailable(std::string_view feature, std::string_view build_flag)
         : std::runtime_error(compose_message(feature, build_flag)) {}