docs: complete validate_path and get_workspace_tab docstrings

Author: clean6378-max-it

api/config_api.py

@@ -65,7 +65,22 @@ def detect_environment() -> Response:
 
 @bp.route("/api/validate-path", methods=["POST"])
 def validate_path() -> tuple[Response, int] | Response:
-    """Same path rules as POST /api/set-workspace: realpath, markers (issue #15)."""
+    """Validate a workspace storage path without persisting it (POST /api/validate-path).
+
+    Uses the same rules as :func:`set_workspace` (realpath, Cursor markers; issue #15).
+
+    Args:
+        path: Workspace storage root from JSON body ``{"path": "..."}``.
+
+    Returns:
+        JSON with ``valid``, ``workspaceCount``, and canonical ``path`` on success.
+        ``valid`` is ``false`` when the path fails validation or contains no
+        workspace folders with ``state.vscdb``. Invalid JSON body returns
+        ``{"valid": false, "error": "invalid JSON body", "workspaceCount": 0}``.
+        Path validation errors return ``{"valid": false, "error": "...", "workspaceCount": 0}``.
+        500 with ``{"valid": false, "error": "Failed to validate path"}`` on
+        unexpected failure.
+    """
     try:
         body = request.get_json(silent=True) or {}
         if not isinstance(body, dict):
@@ -102,6 +117,8 @@ def validate_path() -> tuple[Response, int] | Response:
             exc_info=True,
         )
         return json_response({"valid": False, "error": "Failed to validate path"}, 500)
+
+
 @bp.route("/api/set-workspace", methods=["POST"])
 def set_workspace() -> tuple[Response, int] | Response:
     """Persist a validated workspace storage path (POST /api/set-workspace).

api/workspaces.py

@@ -75,6 +75,8 @@ def list_workspaces() -> tuple[Response, int] | Response:
     except Exception:
         _logger.exception("Failed to get workspaces")
         return json_response({"error": "Failed to get workspaces"}, 500)
+
+
 # ---------------------------------------------------------------------------
 # GET /api/workspaces/<id>
 # ---------------------------------------------------------------------------
@@ -158,6 +160,8 @@ def get_workspace(workspace_id: str) -> tuple[Response, int] | Response:
     except Exception:
         _logger.exception("Failed to get workspace")
         return json_response({"error": "Failed to get workspace"}, 500)
+
+
 # ---------------------------------------------------------------------------
 # GET /api/workspaces/<id>/tabs
 # ---------------------------------------------------------------------------
@@ -198,6 +202,8 @@ def get_workspace_tabs(workspace_id: str) -> tuple[Response, int] | Response:
     except Exception:
         _logger.exception("Failed to get workspace tabs")
         return json_response({"error": "Failed to get workspace tabs"}, 500)
+
+
 # ---------------------------------------------------------------------------
 # GET /api/workspaces/<id>/tabs/<composer_id>
 # ---------------------------------------------------------------------------
@@ -207,12 +213,15 @@ def get_workspace_tab(workspace_id: str, composer_id: str) -> tuple[Response, in
     """Lazy-load one conversation tab (GET /api/workspaces/<id>/tabs/<composer_id>).
 
     Args:
-        workspace_id: IDE workspace folder name (CLI workspaces return 400).
+        workspace_id: Storage folder name, ``global`` for unassigned chats, or
+            ``cli:<project_id>`` (CLI workspaces return 400).
         composer_id: Composer UUID to load.
 
     Returns:
-        Single-tab JSON from :func:`services.workspace_tabs.assemble_single_tab`.
-        400 for CLI workspaces; 500 on unexpected failure.
+        Single-tab JSON from :func:`services.workspace_tabs.assemble_single_tab`
+        (typically ``{"tab": {...}}`` with optional ``warnings``). 400 for CLI
+        workspaces; 404 when global storage is missing, the composer is not found,
+        or it is not assigned to *workspace_id*; 500 on unexpected failure.
     """
     if workspace_id.startswith("cli:"):
         return json_response({"error": "Per-tab lazy load is not supported for CLI workspaces"}, 400)