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/firewall.py

@@ -21,6 +21,16 @@ bp = Blueprint("firewall", __name__)
 
 @bp.route("/config", methods=["GET"])
 def config_list():
+    """Retrieve the current firewall declarative configuration.
+
+    Returns JSON containing the full firewall config from the daemon.
+
+    Endpoint:
+        GET /api/firewall/config
+
+    Returns:
+        JSON response with the config data or an error message.
+    """
     try:
         return _ok(get("/firewall/config"))
     except RuntimeError as exc:
@@ -30,6 +40,20 @@ def config_list():
 
 @bp.route("/config", methods=["POST"])
 def config_save():
+    """Save a new firewall declarative configuration.
+
+    Validates that the request body contains a ``zones`` dict, forwards
+    to the daemon, and returns the pending state including unmanaged zones.
+
+    Endpoint:
+        POST /api/firewall/config
+
+    Args:
+        body: JSON with ``zones`` dict mapping zone names to zone configs.
+
+    Returns:
+        JSON with ``config_saved`` flag and pending apply information.
+    """
     body = request.get_json(silent=True) or {}
     if "zones" not in body:
         return _error("'zones' key is required", 400)
@@ -64,6 +88,20 @@ def config_save():
 
 @bp.route("/config", methods=["PATCH"])
 def patch_config():
+    """Partially update the firewall declarative configuration.
+
+    Accepts a JSON body and forwards it as a patch to the daemon config
+    endpoint, returning the updated pending state.
+
+    Endpoint:
+        PATCH /api/firewall/config
+
+    Args:
+        body: JSON object with configuration fields to patch.
+
+    Returns:
+        JSON with ``config_saved`` flag and pending apply information.
+    """
     body = request.get_json(silent=True) or {}
     if not isinstance(body, dict):
         return _error("Request body must be a JSON object", 400)
@@ -95,6 +133,17 @@ def patch_config():
 
 @bp.route("/config/apply", methods=["POST"])
 def config_apply_bp():
+    """Apply any pending firewall configuration changes.
+
+    Triggers the daemon to apply saved declarative config to the live
+    firewalld instance.
+
+    Endpoint:
+        POST /api/firewall/config/apply
+
+    Returns:
+        JSON with ``applied_zones`` list or an error message.
+    """
     try:
         result = post("/firewall/config/apply")
         logger.info("Firewall config applied: %s", result.get("applied_zones", []))
@@ -106,6 +155,17 @@ def config_apply_bp():
 
 @bp.route("/config/pending", methods=["GET"])
 def config_pending_bp():
+    """Check the pending firewall configuration state.
+
+    Returns information about unsaved changes, whether an apply is
+    needed, and any unmanaged zones detected on the system.
+
+    Endpoint:
+        GET /api/firewall/config/pending
+
+    Returns:
+        JSON with pending changes and apply status.
+    """
     try:
         return _ok(get("/firewall/config/pending"))
     except RuntimeError as exc:
@@ -120,6 +180,14 @@ def config_pending_bp():
 
 @bp.route("/zones", methods=["GET"])
 def list_zones():
+    """List all active and available firewall zones.
+
+    Endpoint:
+        GET /api/firewall/zones
+
+    Returns:
+        JSON with ``active`` zones dict and ``available`` zones list.
+    """
     try:
         data = get("/firewall/zones")
         return _ok(
@@ -132,6 +200,17 @@ def list_zones():
 
 @bp.route("/zones/<name>", methods=["GET"])
 def zone_details(name: str):
+    """Retrieve details for a specific firewall zone.
+
+    Endpoint:
+        GET /api/firewall/zones/<name>
+
+    Args:
+        name: Name of the zone to look up.
+
+    Returns:
+        JSON with zone configuration details or 404 error.
+    """
     try:
         info = get("/firewall/zones/info", {"zone": name})
         return _ok(info)
@@ -145,6 +224,17 @@ def zone_details(name: str):
 
 @bp.route("/zones", methods=["POST"])
 def create_zone_bp():
+    """Create a new firewall zone.
+
+    Endpoint:
+        POST /api/firewall/zones
+
+    Args:
+        body: JSON with ``name`` (required) and optional ``target`` string.
+
+    Returns:
+        JSON confirmation or error if the zone already exists.
+    """
     body = request.get_json(silent=True) or {}
     zone_name = body.get("name", "").strip()
     target = body.get("target", "default").strip() or "default"
@@ -164,6 +254,17 @@ def create_zone_bp():
 
 @bp.route("/zones/<name>", methods=["DELETE"])
 def delete_zone_bp(name: str):
+    """Delete a firewall zone by name.
+
+    Endpoint:
+        DELETE /api/firewall/zones/<name>
+
+    Args:
+        name: Name of the zone to delete.
+
+    Returns:
+        JSON confirmation or 404 if the zone does not exist.
+    """
     try:
         delete("/firewall/zones/delete", {"zone": name})
         logger.info("Zone '%s' deleted via API", name)
@@ -183,6 +284,20 @@ def delete_zone_bp(name: str):
 
 @bp.route("/zones/<name>/interfaces", methods=["POST"])
 def set_zone_interfaces_bp(name: str):
+    """Set the network interfaces assigned to a firewall zone.
+
+    Replaces all existing interfaces for the zone with the provided list.
+
+    Endpoint:
+        POST /api/firewall/zones/<name>/interfaces
+
+    Args:
+        name: Zone name.
+        body: JSON with ``interfaces`` list of interface names.
+
+    Returns:
+        JSON confirmation with zone and updated interfaces list.
+    """
     body = request.get_json(silent=True) or {}
     interfaces = body.get("interfaces", [])
     if not isinstance(interfaces, list):
@@ -209,6 +324,20 @@ def set_zone_interfaces_bp(name: str):
 
 @bp.route("/zones/<name>/services", methods=["POST"])
 def set_zone_services_bp(name: str):
+    """Set the allowed services for a firewall zone.
+
+    Replaces all existing services for the zone with the provided list.
+
+    Endpoint:
+        POST /api/firewall/zones/<name>/services
+
+    Args:
+        name: Zone name.
+        body: JSON with ``services`` list of service names.
+
+    Returns:
+        JSON confirmation with zone and updated services list.
+    """
     body = request.get_json(silent=True) or {}
     services = body.get("services", [])
     if not isinstance(services, list):
@@ -234,6 +363,14 @@ def set_zone_services_bp(name: str):
 
 @bp.route("/services", methods=["GET"])
 def list_services():
+    """List all available firewall services.
+
+    Endpoint:
+        GET /api/firewall/services
+
+    Returns:
+        JSON with the list of available service names.
+    """
     try:
         return _ok(get("/firewall/services"))
     except RuntimeError as exc:
@@ -243,6 +380,14 @@ def list_services():
 
 @bp.route("/interfaces", methods=["GET"])
 def list_interfaces():
+    """List all available network interfaces.
+
+    Endpoint:
+        GET /api/firewall/interfaces
+
+    Returns:
+        JSON with the list of available interface names.
+    """
     try:
         return _ok(get("/firewall/interfaces"))
     except RuntimeError as exc:
@@ -257,6 +402,17 @@ def list_interfaces():
 
 @bp.route("/rich-rules", methods=["POST"])
 def add_rich_rule_bp():
+    """Add a rich rule to a firewall zone.
+
+    Endpoint:
+        POST /api/firewall/rich-rules
+
+    Args:
+        body: JSON with ``zone`` (zone name) and ``rule`` (XML rule string).
+
+    Returns:
+        JSON with zone, generated rule ID, and rule string.
+    """
     body = request.get_json(silent=True) or {}
     zone = body.get("zone", "").strip()
     rule = body.get("rule", "").strip()
@@ -276,6 +432,17 @@ def add_rich_rule_bp():
 
 @bp.route("/rich-rules/<zone>", methods=["GET"])
 def list_rich_rules(zone: str):
+    """List rich rules for a specific firewall zone.
+
+    Endpoint:
+        GET /api/firewall/rich-rules/<zone>
+
+    Args:
+        zone: Zone name to list rules for.
+
+    Returns:
+        JSON with list of rich rule entries for the zone.
+    """
     try:
         return _ok(get("/firewall/rich-rules", {"zone": zone}))
     except RuntimeError as exc:
@@ -285,6 +452,18 @@ def list_rich_rules(zone: str):
 
 @bp.route("/rich-rules/<zone>/<rule_id>", methods=["DELETE"])
 def remove_rich_rule_bp(zone: str, rule_id: str):
+    """Remove a rich rule from a firewall zone by ID.
+
+    Endpoint:
+        DELETE /api/firewall/rich-rules/<zone>/<rule_id>
+
+    Args:
+        zone: Zone name.
+        rule_id: Rule identifier.
+
+    Returns:
+        JSON confirmation or 404 if the rule does not exist.
+    """
     try:
         delete("/firewall/rich-rules/remove", {"zone": zone, "id": rule_id})
         logger.info("Rich rule '%s' removed from zone '%s'", rule_id, zone)
@@ -304,6 +483,17 @@ def remove_rich_rule_bp(zone: str, rule_id: str):
 
 @bp.route("/masquerade", methods=["POST"])
 def set_masquerade_bp():
+    """Enable or disable masquerade (NAT) on a firewall zone.
+
+    Endpoint:
+        POST /api/firewall/masquerade
+
+    Args:
+        body: JSON with ``zone`` (zone name) and ``enable`` (boolean).
+
+    Returns:
+        JSON confirmation with zone and masquerade status.
+    """
     body = request.get_json(silent=True) or {}
     zone = body.get("zone", "").strip()
     enable = body.get("enable")
@@ -332,6 +522,18 @@ def set_masquerade_bp():
 
 @bp.route("/forward-port", methods=["POST"])
 def add_forward_port_bp():
+    """Add a port forwarding rule to a firewall zone.
+
+    Endpoint:
+        POST /api/firewall/forward-port
+
+    Args:
+        body: JSON with ``zone`` (zone name), ``port`` (int), ``proto``
+            (tcp/udp), optional ``toaddr`` and ``toport``.
+
+    Returns:
+        JSON confirmation with zone, generated ID, port, and protocol.
+    """
     body = request.get_json(silent=True) or {}
     zone = body.get("zone", "").strip()
     port = body.get("port")
@@ -373,6 +575,19 @@ def add_forward_port_bp():
 
 @bp.route("/forward-port/<zone>/<int:port>/<proto>", methods=["DELETE"])
 def remove_forward_port_bp(zone: str, port: int, proto: str):
+    """Remove a port forwarding rule from a firewall zone.
+
+    Endpoint:
+        DELETE /api/firewall/forward-port/<zone>/<port>/<proto>
+
+    Args:
+        zone: Zone name.
+        port: Port number.
+        proto: Protocol (tcp/udp).
+
+    Returns:
+        JSON confirmation or 404 if the rule does not exist.
+    """
     try:
         delete(
             "/firewall/forward-port/remove",