docs: Add docblocks to interceptor classes

- Document which attributes each interceptor binds to
- Clarify CQRS query (onGet) vs command (onPut/onPatch/onDelete) distinction
- Add links to attribute classes and manual sections
- Explain cache behavior and ETag generation differences

Interceptors documented:
- CacheInterceptor: TTL-based caching for queries
- CommandInterceptor: Cache invalidation for commands
- HttpCacheInterceptor: HTTP Cache-Control header
- DonutCacheInterceptor: Donut caching for queries
- DonutCacheableResponseInterceptor: Full response caching for queries
- DonutCommandInterceptor: Donut cache invalidation for commands
- RefreshInterceptor: Cache refresh for non-Cacheable classes

Author: koriym

src/CacheInterceptor.php

@@ -17,6 +17,16 @@
 
 use const E_USER_WARNING;
 
+/**
+ * Interceptor for TTL-based caching on CQRS queries with #[Cacheable]
+ *
+ * Bound to query methods (onGet) of classes marked with #[Cacheable].
+ * Retrieves cached resource state if available, otherwise executes
+ * the method and stores the result with configured TTL.
+ *
+ * @see \BEAR\RepositoryModule\Annotation\Cacheable
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#cacheable
+ */
 final readonly class CacheInterceptor implements MethodInterceptor
 {
     public function __construct(

src/CommandInterceptor.php

@@ -12,6 +12,16 @@
 use Ray\Aop\MethodInterceptor;
 use Ray\Aop\MethodInvocation;
 
+/**
+ * Interceptor for cache invalidation on CQRS commands with #[Purge] or #[Refresh]
+ *
+ * Bound to command methods (onPut/onPatch/onDelete) of #[Cacheable] classes.
+ * Executes cache invalidation after successful write operations.
+ *
+ * @see \BEAR\RepositoryModule\Annotation\Purge
+ * @see \BEAR\RepositoryModule\Annotation\Refresh
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#tag-based-cache-invalidation
+ */
 final readonly class CommandInterceptor implements MethodInterceptor
 {
     /** @param CommandInterface[] $commands */

src/DonutCacheInterceptor.php

@@ -4,6 +4,16 @@
 
 namespace BEAR\QueryRepository;
 
+/**
+ * Interceptor for donut caching on CQRS queries with #[DonutCache]
+ *
+ * Bound to query methods (onGet) or individual methods marked with #[DonutCache].
+ * Caches only the cacheable portions, excluding non-cacheable embedded content.
+ * No ETag is generated for the entire response.
+ *
+ * @see \BEAR\RepositoryModule\Annotation\DonutCache
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#donut-cache
+ */
 final class DonutCacheInterceptor extends AbstractDonutCacheInterceptor
 {
     protected const IS_ENTIRE_CONTENT_CACHEABLE = false;

src/DonutCacheableResponseInterceptor.php

@@ -4,6 +4,16 @@
 
 namespace BEAR\QueryRepository;
 
+/**
+ * Interceptor for full response caching on CQRS queries with #[CacheableResponse]
+ *
+ * Bound to query methods (onGet) of classes marked with #[CacheableResponse].
+ * Caches the entire response and generates an ETag for conditional requests.
+ * Enables 304 (Not Modified) responses for efficient network transfer.
+ *
+ * @see \BEAR\RepositoryModule\Annotation\CacheableResponse
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#event-driven-content
+ */
 final class DonutCacheableResponseInterceptor extends AbstractDonutCacheInterceptor
 {
     protected const IS_ENTIRE_CONTENT_CACHEABLE = true;

src/DonutCommandInterceptor.php

@@ -19,6 +19,16 @@
 use function is_callable;
 use function sprintf;
 
+/**
+ * Interceptor for donut cache invalidation on CQRS commands
+ *
+ * Bound to command methods (onPut/onPatch/onDelete) of classes marked with #[CacheableResponse].
+ * Refreshes donut cache and resource state after successful write operations.
+ *
+ * @see \BEAR\RepositoryModule\Annotation\CacheableResponse
+ * @see \BEAR\RepositoryModule\Annotation\DonutCache
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#event-driven-content
+ */
 final readonly class DonutCommandInterceptor implements MethodInterceptor
 {
     public function __construct(

src/HttpCacheInterceptor.php

@@ -14,6 +14,16 @@
 
 use function assert;
 
+/**
+ * Interceptor for HTTP Cache-Control header with #[HttpCache] or #[NoHttpCache]
+ *
+ * Bound to onGet methods of classes marked with #[HttpCache] or #[NoHttpCache].
+ * Sets the Cache-Control header based on attribute configuration for HTTP caching.
+ *
+ * @see \BEAR\RepositoryModule\Annotation\HttpCache
+ * @see \BEAR\RepositoryModule\Annotation\NoHttpCache
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html
+ */
 final class HttpCacheInterceptor implements MethodInterceptor
 {
     /**

src/RefreshInterceptor.php

@@ -11,6 +11,16 @@
 use Ray\Aop\MethodInterceptor;
 use Ray\Aop\MethodInvocation;
 
+/**
+ * Interceptor for cache refresh commands with #[Purge] or #[Refresh]
+ *
+ * Bound to methods marked with #[Purge] or #[Refresh] on non-Cacheable classes.
+ * Executes cache invalidation commands after successful method execution.
+ *
+ * @see \BEAR\RepositoryModule\Annotation\Purge
+ * @see \BEAR\RepositoryModule\Annotation\Refresh
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#event-driven-content
+ */
 final readonly class RefreshInterceptor implements MethodInterceptor
 {
     public function __construct(