docs: add documentation addressing PR review comments

- Add comment explaining thread-local Redis client requirement (async
  clients are bound to specific event loops)
- Complete _exec_fallback docstring with all parameters
- Improve RedisValue docstring explaining its role in invalidation
- Add class and field docstrings to GCacheGlobalState
- Document Fallback type alias
- Complete invalidate method docstring with all parameters
- Add LocalCache class docstring explaining its role and limitations

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: lan17

src/gcache/_internal/cache_interface.py

@@ -4,6 +4,8 @@
 
 from gcache.config import CacheConfigProvider, CacheLayer, GCacheKey, GCacheKeyConfig
 
+#: Async callable that fetches the actual value on cache miss.
+#: Invoked by cache implementations when the requested key is not found or is stale.
 Fallback = Callable[..., Awaitable[Any]]
 
 
@@ -37,14 +39,17 @@ async def delete(self, key: GCacheKey) -> bool:
 
     async def invalidate(self, key_type: str, id: str, future_buffer_ms: int) -> None:
         """
-        Invalidate all caches matching key_type and id at this point in time.
+        Invalidate all cache entries matching key_type and id.
 
-        Any cache entry that was created before now + future_buffer_ms will be considered invalid.
+        Sets a watermark timestamp so that any cached value created before
+        (now + future_buffer_ms) is considered stale on subsequent reads.
 
-        :param key_type:
-        :param id:
-        :param future_buffer_ms: Invalidate cache into the future. Useful to avoid stale read -> write scenarios.
-        :return:
+        :param key_type: The entity type (e.g., 'user', 'project') matching the
+            key_type used in @cached decorators.
+        :param id: The entity identifier to invalidate.
+        :param future_buffer_ms: Extends invalidation window into the future.
+            Useful to handle race conditions where a read starts before a write
+            completes but finishes after, preventing caching of stale data.
         """
         pass
 

src/gcache/_internal/local_cache.py

@@ -11,11 +11,21 @@
 
 
 class LocalCache(CacheInterface):
+    """
+    In-memory cache layer using TTLCache from cachetools.
+
+    Maintains a separate TTLCache instance per use_case, each with a configurable
+    TTL and a max size of LOCAL_CACHE_MAX_SIZE entries. This is the first layer
+    in the cache chain, checked before Redis.
+
+    Note: LocalCache does not support invalidation (watermarks). If you need
+    invalidation support, rely on the Redis layer with track_for_invalidation=True.
+    """
+
     def __init__(self, cache_config_provider: CacheConfigProvider):
         super().__init__(cache_config_provider)
-        # Dict of usecase -> ttl cache instance.
-        self.caches: dict[str, TTLCache] = {}
-        self.lock = asyncio.Lock()
+        self.caches: dict[str, TTLCache] = {}  # use_case -> TTLCache instance
+        self.lock = asyncio.Lock()  # Protects cache creation
 
     async def _get_ttl_cache(self, key: GCacheKey) -> TTLCache:
         cache = self.caches.get(key.use_case, None)

src/gcache/_internal/redis_cache.py

@@ -20,11 +20,14 @@
 @dataclass(frozen=True, slots=True)
 class RedisValue:
     """
-    Wrap actual payload with created timestamp.
+    Wrapper around cached payload that includes creation timestamp.
+
+    The timestamp enables cache invalidation: when a watermark is set for a key,
+    any cached value with created_at_ms <= watermark is considered stale.
     """
 
-    created_at_ms: int
-    payload: Any
+    created_at_ms: int  # Unix timestamp in milliseconds when this value was cached
+    payload: Any  # The actual cached data (may be serialized if Serializer is used)
 
 
 def create_default_redis_client_factory(
@@ -70,6 +73,11 @@ def __init__(
         """
         super().__init__(cache_config_provider)
         self._client_factory = client_factory
+        # Thread-local storage is required because async redis-py clients maintain
+        # internal state (connection pool, pending requests) bound to a specific event loop.
+        # Since gcache runs sync cached functions in EventLoopThread workers (each with its
+        # own event loop), sharing a client across threads causes "attached to a different
+        # event loop" RuntimeError. One client per thread ensures correct event loop binding.
         self._thread_local = threading.local()
 
     @property
@@ -91,9 +99,17 @@ async def _exec_fallback(
         fallback: Fallback,
     ) -> Any:
         """
-        Execute fallback and store it in cache then return it's return value.
-        :param fallback:
-        :return:
+        Execute the fallback function, optionally cache the result, and return it.
+
+        The result is stored in cache unless there's an active invalidation window
+        (watermark_ms is in the future). This prevents caching potentially stale data
+        that was fetched during an invalidation period.
+
+        :param key: Cache key for storing the result.
+        :param watermark_ms: Invalidation watermark timestamp in milliseconds, or None.
+            If set and greater than current time, the result is not cached.
+        :param fallback: Async function that fetches the actual value.
+        :return: The value returned by the fallback function.
         """
         val = await fallback()
         if watermark_ms is None or watermark_ms < time.time() * 1e3:

src/gcache/_internal/state.py

@@ -4,12 +4,23 @@
 from pydantic import BaseModel, ConfigDict
 
 
-# Global state is needed to allow reconfiguration when GCache is instantiated.
-# This is fine because GCache is guaranteed to be a singleton.
 class GCacheGlobalState(BaseModel):
+    """
+    Global configuration state shared across all gcache components.
+
+    This state is modified when GCache is instantiated and read by cache implementations,
+    key builders, and logging throughout the library. Global state is acceptable here
+    because GCache enforces a singleton pattern.
+    """
+
     urn_prefix: str = "urn"
+    """Namespace prefix prepended to all cache key URNs (e.g., 'urn:user:123#use_case')."""
+
     logger: Logger | LoggerAdapter = getLogger(__name__)
+    """Logger used for debug messages and error reporting throughout gcache."""
+
     gcache_instantiated: bool = False
+    """Singleton guard: set to True when GCache is created, prevents duplicate instances."""
 
     model_config = ConfigDict(arbitrary_types_allowed=True)