docs: add docstrings to all API endpoints and daemon handlers

Add comprehensive docstrings to firewall, DHCP, proxy, wireguard, certs,
and logs API endpoints. Document parameters, return values, and error cases
for the documentation system.

webui/api/wireguard.py

@@ -16,6 +16,14 @@ bp = Blueprint("wireguard", __name__)
 
 @bp.route("/config", methods=["GET"])
 def get_config_bp():
+    """Get the current WireGuard configuration.
+
+    Endpoint: GET /api/wireguard/config
+
+    Returns:
+        JSON response with the WireGuard config on success, or an error
+        response on failure.
+    """
     try:
         return _ok(get("/wireguard/config"))
     except RuntimeError as exc:
@@ -25,6 +33,18 @@ def get_config_bp():
 
 @bp.route("/config", methods=["POST"])
 def post_config():
+    """Create or fully replace the WireGuard configuration.
+
+    Endpoint: POST /api/wireguard/config
+
+    Args:
+        body: JSON body with the configuration. If an ``interface`` key
+            is present, the private key will be stripped before forwarding.
+
+    Returns:
+        Success response on acceptance, 400 on validation failure, or 500
+        on server error.
+    """
     body = request.get_json(silent=True) or {}
     if not isinstance(body, dict):
         return _error("Request body must be a JSON object", 400)
@@ -45,6 +65,18 @@ def post_config():
 
 @bp.route("/config", methods=["PATCH"])
 def patch_config():
+    """Partially update the WireGuard configuration.
+
+    Endpoint: PATCH /api/wireguard/config
+
+    Args:
+        body: JSON body with the fields to update. If an ``interface``
+            key is present, the private key will be stripped before forwarding.
+
+    Returns:
+        Success response on acceptance, 400 on validation failure, or 500
+        on server error.
+    """
     body = request.get_json(silent=True) or {}
     if not isinstance(body, dict):
         return _error("Request body must be a JSON object", 400)
@@ -66,6 +98,13 @@ def patch_config():
 
 @bp.route("/apply", methods=["POST"])
 def apply_bp():
+    """Apply the current WireGuard configuration to the live tunnel.
+
+    Endpoint: POST /api/wireguard/apply
+
+    Returns:
+        Success response on acceptance, or 500 on server error.
+    """
     try:
         post("/wireguard/apply")
         logger.info("WireGuard tunnel applied via API")
@@ -77,6 +116,13 @@ def apply_bp():
 
 @bp.route("/up", methods=["POST"])
 def up_bp():
+    """Bring the WireGuard tunnel interface up.
+
+    Endpoint: POST /api/wireguard/up
+
+    Returns:
+        Success response on acceptance, or 500 on server error.
+    """
     try:
         post("/wireguard/apply")
         logger.info("WireGuard tunnel started via API")
@@ -88,6 +134,13 @@ def up_bp():
 
 @bp.route("/down", methods=["POST"])
 def down_bp():
+    """Bring the WireGuard tunnel interface down.
+
+    Endpoint: POST /api/wireguard/down
+
+    Returns:
+        Success response on acceptance, or 500 on server error.
+    """
     try:
         post("/wireguard/down")
         logger.info("WireGuard tunnel brought down via API")
@@ -99,6 +152,14 @@ def down_bp():
 
 @bp.route("/status", methods=["GET"])
 def status_bp():
+    """Get the current WireGuard tunnel status.
+
+    Endpoint: GET /api/wireguard/status
+
+    Returns:
+        JSON response with the tunnel status on success, or an error
+        response on failure.
+    """
     try:
         return _ok(get("/wireguard/status"))
     except RuntimeError as exc:
@@ -108,6 +169,13 @@ def status_bp():
 
 @bp.route("/initialize", methods=["POST"])
 def initialize_bp():
+    """Initialize WireGuard for first-time use.
+
+    Endpoint: POST /api/wireguard/initialize
+
+    Returns:
+        Success response on acceptance, or 500 on server error.
+    """
     try:
         post("/wireguard/initialize")
         logger.info("WireGuard initialized via API")
@@ -119,6 +187,21 @@ def initialize_bp():
 
 @bp.route("/peers", methods=["POST"])
 def add_peer_bp():
+    """Add a new peer to the WireGuard configuration.
+
+    Endpoint: POST /api/wireguard/peers
+
+    Args:
+        name: Peer display name (required).
+        endpoint: Optional peer endpoint address.
+        allowed_ips: Optional list of allowed IP CIDRs.
+        persistent_keepalive: Optional keepalive interval in seconds.
+        preshared_key: Optional pre-shared key in hex.
+
+    Returns:
+        JSON response with the created peer on success, 400 on validation
+        failure, or 500 on server error.
+    """
     body = request.get_json(silent=True) or {}
     name = body.get("name", "").strip()
     if not name:
@@ -146,6 +229,17 @@ def add_peer_bp():
 
 @bp.route("/peers/<name>", methods=["DELETE"])
 def remove_peer_bp(name):
+    """Remove a peer from the WireGuard configuration.
+
+    Endpoint: DELETE /api/wireguard/peers/<name>
+
+    Args:
+        name: Peer name to remove (from URL path).
+
+    Returns:
+        Success response with peer name on removal, 404 if peer not found,
+        or 500 on server error.
+    """
     try:
         delete("/wireguard/peers/remove", {"name": name})
         logger.info("WireGuard peer '%s' removed via API", name)
@@ -160,6 +254,14 @@ def remove_peer_bp(name):
 
 @bp.route("/peers", methods=["GET"])
 def peers_bp():
+    """List all configured WireGuard peers.
+
+    Endpoint: GET /api/wireguard/peers
+
+    Returns:
+        JSON response with the peers list on success, or an error response
+        on failure.
+    """
     try:
         return _ok(get("/wireguard/peers"))
     except RuntimeError as exc:
@@ -169,6 +271,14 @@ def peers_bp():
 
 @bp.route("/peer-status", methods=["GET"])
 def peer_status_bp():
+    """Get real-time status information for all WireGuard peers.
+
+    Endpoint: GET /api/wireguard/peer-status
+
+    Returns:
+        JSON response with peer status on success, or an error response
+        on failure.
+    """
     try:
         return _ok(get("/wireguard/peer-status"))
     except RuntimeError as exc:
@@ -178,6 +288,18 @@ def peer_status_bp():
 
 @bp.route("/generate-client", methods=["POST"])
 def generate_client_bp():
+    """Generate a WireGuard client configuration file for a peer.
+
+    Endpoint: POST /api/wireguard/generate-client
+
+    Args:
+        name: Peer name (required).
+        server_endpoint: Server endpoint address for the client config (required).
+
+    Returns:
+        JSON response with the generated config string on success, 404 if
+        peer not found, 400 on validation failure, or 500 on server error.
+    """
     body = request.get_json(silent=True) or {}
     name = body.get("name", "").strip()
     if not name: