From 47c92633797cdd813c814cf53fee2c01a546c371 Mon Sep 17 00:00:00 2001
From: Ray <mailtangyu@gmail.com>
Date: Wed, 22 Jul 2026 12:33:30 +0800
Subject: [PATCH] chore: trim fix-rationale comments

---
 pageindex/backend/cloud.py  | 5 -----
 pageindex/cloud_api.py      | 2 --
 pageindex/config.py         | 3 +--
 pageindex/index/pipeline.py | 3 ---
 pageindex/storage/sqlite.py | 2 --
 5 files changed, 1 insertion(+), 14 deletions(-)

diff --git a/pageindex/backend/cloud.py b/pageindex/backend/cloud.py
index 44ca151..57c5517 100644
--- a/pageindex/backend/cloud.py
+++ b/pageindex/backend/cloud.py
@@ -144,8 +144,6 @@ class CloudBackend:
                 self._warn_folder_upgrade()
                 self._folder_id_cache[name] = None
             elif e.status_code == 400 and "already exists" in str(e):
-                # Duplicate-name 400, for parity with the local backend's
-                # error taxonomy.
                 raise CollectionAlreadyExistsError(
                     f"Collection '{name}' already exists") from e
             else:
@@ -211,9 +209,6 @@ class CloudBackend:
         except CollectionNotFoundError:
             return  # already gone — delete is idempotent
         if folder_id:
-            # The cloud API has no folder-deletion endpoint (only POST /folder
-            # and GET /folders exist) — fail clearly instead of issuing a
-            # request that can only 404.
             raise PageIndexError(
                 f"Deleting a cloud collection is not supported by the PageIndex "
                 f"API — delete folder '{name}' in the dashboard "
diff --git a/pageindex/cloud_api.py b/pageindex/cloud_api.py
index b8866ac..36767e3 100644
--- a/pageindex/cloud_api.py
+++ b/pageindex/cloud_api.py
@@ -53,8 +53,6 @@ class LegacyCloudAPI:
         # forever. Streamed responses get a longer read timeout since it
         # applies between chunks, not to the whole response.
         kwargs.setdefault("timeout", 120 if kwargs.get("stream") else 30)
-        # Transport errors propagate raw (0.2.x contract) — they must escape
-        # is_retrieval_ready's except-PageIndexAPIError, not read as "not ready".
         response = requests.request(
             method,
             f"{self.base_url}{path}",
diff --git a/pageindex/config.py b/pageindex/config.py
index 3433860..46b366c 100644
--- a/pageindex/config.py
+++ b/pageindex/config.py
@@ -51,8 +51,7 @@ class IndexConfig(BaseModel):
     def from_yaml(cls, path: str = None, **overrides) -> "IndexConfig":
         """Load config from a YAML file ("yes"/"no" accepted for booleans);
         keyword overrides take precedence. Defaults to the package config.yaml.
-        Unknown YAML keys are ignored with a warning (legacy config.yaml
-        tolerance); unknown keyword overrides still raise."""
+        Unknown YAML keys are ignored with a warning."""
         import yaml
         if path is None:
             path = os.path.join(os.path.dirname(__file__), "config.yaml")
diff --git a/pageindex/index/pipeline.py b/pageindex/index/pipeline.py
index d828450..9e9556d 100644
--- a/pageindex/index/pipeline.py
+++ b/pageindex/index/pipeline.py
@@ -111,9 +111,6 @@ def build_index(parsed: ParsedDocument, model: str = None, opt=None) -> dict:
             "structure": structure,
         }
 
-        # Description requires summaries (legacy gating): the clean structure
-        # fed to the LLM carries only titles/summaries, so without summaries
-        # the description would be generated from bare titles.
         if opt.if_add_node_summary and opt.if_add_doc_description:
             clean_structure = create_clean_structure_for_description(structure)
             result["doc_description"] = generate_doc_description(
diff --git a/pageindex/storage/sqlite.py b/pageindex/storage/sqlite.py
index 945eec5..9526833 100644
--- a/pageindex/storage/sqlite.py
+++ b/pageindex/storage/sqlite.py
@@ -210,8 +210,6 @@ class SQLiteStorage:
     def list_documents(self, collection: str) -> list[dict]:
         conn = self._get_conn()
         rows = conn.execute(
-            # Newest first, matching the cloud API's createdAt DESC order;
-            # rowid breaks same-second ties by insertion order.
             "SELECT doc_id, doc_name, doc_description, doc_type FROM documents WHERE collection_name = ? ORDER BY created_at DESC, rowid DESC",
             (collection,),
         ).fetchall()