docs: Add interceptor binding information to cache attributes

- Document which interceptors are bound to each cache attribute
- Add direct links to BEAR.Sunday manual sections with hash fragments
- Improve code readability for developers understanding the caching system

Attributes updated:
- Cacheable: CacheInterceptor, CommandInterceptor
- HttpCache/NoHttpCache: HttpCacheInterceptor
- Purge/Refresh: RefreshInterceptor, CommandInterceptor
- DonutCache: DonutCacheInterceptor
- CacheableResponse: DonutCacheableResponseInterceptor, DonutCommandInterceptor
- RefreshCache: DonutCacheInterceptor

Author: koriym

src-annotation/Cacheable.php

@@ -6,6 +6,15 @@
 
 use Attribute;
 
+/**
+ * Marks a resource class as cacheable with TTL-based caching
+ *
+ * Interceptors bound:
+ * - CacheInterceptor (onGet methods)
+ * - CommandInterceptor (onPut/onPatch/onDelete methods)
+ *
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#cacheable
+ */
 #[Attribute(Attribute::TARGET_CLASS)]
 final class Cacheable
 {

src-annotation/CacheableResponse.php

@@ -10,9 +10,15 @@
 use BEAR\QueryRepository\DonutCommandInterceptor;
 
 /**
+ * Marks a resource for full response caching (entire content is cacheable)
+ *
+ * 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 DonutCacheableResponseInterceptor
- * @see DonutCommandInterceptor
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#donut-cache
  */
 #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
 final class CacheableResponse

src-annotation/DonutCache.php

@@ -9,9 +9,13 @@
 use BEAR\QueryRepository\DonutCommandInterceptor;
 
 /**
+ * Marks a resource for donut caching (partial caching with embedded dynamic content)
+ *
+ * Interceptors bound:
+ * - DonutCacheInterceptor (onGet methods when applied to class, or any method when applied to method)
+ *
  * @see DonutCacheModule
- * @see DonutCacheInterceptor
- * @see DonutCommandInterceptor
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#donut-cache
  */
 #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
 final class DonutCache

src-annotation/HttpCache.php

@@ -15,7 +15,11 @@
  *
  * Builds a complex Cache-Control header
  *
+ * Interceptors bound:
+ * - HttpCacheInterceptor (onGet methods)
+ *
  * @see HttpCacheInterceptor
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html
  */
 #[Attribute(Attribute::TARGET_CLASS)]
 final class HttpCache extends AbstractCacheControl

src-annotation/NoHttpCache.php

@@ -12,7 +12,11 @@
  *
  * Simplified notation to say that you don't want anything cached
  *
+ * Interceptors bound:
+ * - HttpCacheInterceptor (onGet methods)
+ *
  * @see HttpCacheInterceptor
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html
  */
 #[Attribute(Attribute::TARGET_CLASS)]
 final class NoHttpCache extends AbstractCacheControl

src-annotation/Purge.php

@@ -6,7 +6,15 @@
 
 use Attribute;
 
-/** @see RefreshInterceptor */
+/**
+ * Purges cache for specified URI after command execution
+ *
+ * Interceptors bound:
+ * - RefreshInterceptor (when applied to non-Cacheable classes)
+ * - CommandInterceptor (when applied to Cacheable classes)
+ *
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#tag-based-cache-invalidation
+ */
 #[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
 final class Purge extends AbstractCommand
 {

src-annotation/Refresh.php

@@ -7,7 +7,15 @@
 use Attribute;
 use BEAR\QueryRepository\RefreshInterceptor;
 
-/** @see RefreshInterceptor */
+/**
+ * Refreshes cache for specified URI after command execution
+ *
+ * Interceptors bound:
+ * - RefreshInterceptor (when applied to non-Cacheable classes)
+ * - CommandInterceptor (when applied to Cacheable classes)
+ *
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#event-driven-content
+ */
 #[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
 final class Refresh extends AbstractCommand
 {

src-annotation/RefreshCache.php

@@ -7,7 +7,14 @@
 use Attribute;
 use BEAR\QueryRepository\DonutCommandInterceptor;
 
-/** @see DonutCommandInterceptor */
+/**
+ * Refreshes donut cache after command execution
+ *
+ * Interceptors bound:
+ * - DonutCacheInterceptor
+ *
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#cache-invalidation
+ */
 #[Attribute(Attribute::TARGET_METHOD)]
 final class RefreshCache
 {