docs: Clarify event-driven content is for fundamentally static content

- Emphasize EDC is for content that is fundamentally static
- Changes are predictable via resource methods (onPut, onDelete, etc.)
- Add 304 Not Modified benefit for network transfer cost reduction

Author: koriym

src-annotation/Cacheable.php

@@ -7,7 +7,11 @@
 use Attribute;
 
 /**
- * Marks a resource class as cacheable with TTL-based caching
+ * Marks a resource class as cacheable with TTL-based expiration
+ *
+ * Traditional time-based caching where cache expires after a specified duration.
+ * For event-driven cache invalidation based on resource dependencies, use
+ * #[CacheableResponse] or #[DonutCache] instead.
  *
  * Interceptors bound:
  * - CacheInterceptor (onGet methods)

src-annotation/CacheableResponse.php

@@ -5,20 +5,24 @@
 namespace BEAR\RepositoryModule\Annotation;
 
 use Attribute;
-use BEAR\QueryRepository\DonutCacheableResponseInterceptor;
 use BEAR\QueryRepository\DonutCacheModule;
-use BEAR\QueryRepository\DonutCommandInterceptor;
 
 /**
- * Marks a resource for full response caching (entire content is cacheable)
+ * Enables event-driven cache invalidation for fully cacheable responses
+ *
+ * For content that is fundamentally static but changes predictably via resource
+ * methods (onPut, onDelete, etc.). Unlike #[Cacheable] which uses TTL-based
+ * expiration, this enables tag-based invalidation driven by resource dependencies.
+ * The entire response is cached and receives an ETag for conditional requests,
+ * enabling 304 (Not Modified) responses to reduce network transfer costs.
  *
  * Interceptors bound:
  * - DonutCacheableResponseInterceptor (onGet methods when applied to class)
  * - DonutCommandInterceptor (onPut/onPatch/onDelete methods when applied to class)
  * - DonutCacheInterceptor (when applied to method)
  *
  * @see DonutCacheModule
- * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#donut-cache
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#event-driven-content
  */
 #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
 final class CacheableResponse

src-annotation/DonutCache.php

@@ -6,10 +6,14 @@
 
 use Attribute;
 use BEAR\QueryRepository\DonutCacheModule;
-use BEAR\QueryRepository\DonutCommandInterceptor;
 
 /**
- * Marks a resource for donut caching (partial caching with embedded dynamic content)
+ * Enables event-driven donut caching for resources with non-cacheable embedded content
+ *
+ * For content that is fundamentally static but changes predictably via resource
+ * methods, with some embedded resources that cannot be cached. Unlike #[Cacheable]
+ * which uses TTL-based expiration, this enables tag-based invalidation. Only
+ * cacheable portions are stored; no ETag is generated for the entire response.
  *
  * Interceptors bound:
  * - DonutCacheInterceptor (onGet methods when applied to class, or any method when applied to method)

src-annotation/Refresh.php

@@ -5,7 +5,6 @@
 namespace BEAR\RepositoryModule\Annotation;
 
 use Attribute;
-use BEAR\QueryRepository\RefreshInterceptor;
 
 /**
  * Refreshes cache for specified URI after command execution

src-annotation/RefreshCache.php

@@ -5,7 +5,6 @@
 namespace BEAR\RepositoryModule\Annotation;
 
 use Attribute;
-use BEAR\QueryRepository\DonutCommandInterceptor;
 
 /**
  * Refreshes donut cache after command execution