docs: enhance code documentation with comprehensive PHPDoc comments

src/Prime/EventDispatcher/Event/RemoveEvent.php

@@ -6,22 +6,36 @@ namespace Flasher\Prime\EventDispatcher\Event;
 
 use Flasher\Prime\Notification\Envelope;
 
+/**
+ * RemoveEvent - Event dispatched when notifications are being removed.
+ *
+ * This event is dispatched when notifications are about to be removed from storage.
+ * It allows listeners to modify which notifications should be removed and which
+ * should be kept. This is used for implementing hopping behavior where notifications
+ * can persist across multiple requests.
+ */
 final class RemoveEvent
 {
     /**
+     * Notification envelopes that should be kept in storage.
+     *
      * @var Envelope[]
      */
     private array $envelopesToKeep = [];
 
     /**
-     * @param Envelope[] $envelopesToRemove
+     * Creates a new RemoveEvent instance.
+     *
+     * @param Envelope[] $envelopesToRemove The notification envelopes initially marked for removal
      */
     public function __construct(private array $envelopesToRemove)
     {
     }
 
     /**
-     * @return Envelope[]
+     * Gets the notification envelopes marked for removal.
+     *
+     * @return Envelope[] The notification envelopes to remove
      */
     public function getEnvelopesToRemove(): array
     {
@@ -29,7 +43,9 @@ final class RemoveEvent
     }
 
     /**
-     * @param Envelope[] $envelopesToRemove
+     * Sets the notification envelopes to be removed.
+     *
+     * @param Envelope[] $envelopesToRemove The notification envelopes to remove
      */
     public function setEnvelopesToRemove(array $envelopesToRemove): void
     {
@@ -37,7 +53,9 @@ final class RemoveEvent
     }
 
     /**
-     * @return Envelope[]
+     * Gets the notification envelopes that should be kept in storage.
+     *
+     * @return Envelope[] The notification envelopes to keep
      */
     public function getEnvelopesToKeep(): array
     {
@@ -45,7 +63,9 @@ final class RemoveEvent
     }
 
     /**
-     * @param Envelope[] $envelopesToKeep
+     * Sets the notification envelopes that should be kept in storage.
+     *
+     * @param Envelope[] $envelopesToKeep The notification envelopes to keep
      */
     public function setEnvelopesToKeep(array $envelopesToKeep): void
     {