docs(replay): Document the two capture strategies (#5848)

SessionCaptureStrategy and BufferCaptureStrategy differ only in when a
recorded segment is sent, but nothing at the top of either class said so.
Add a short KDoc to each pointing at the other, covering how the mode is
selected, when segments are sent, and why ReplayIntegration pauses session
mode while buffer mode keeps recording.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: runningcode

sentry-android-replay/src/main/java/io/sentry/android/replay/capture/BufferCaptureStrategy.kt

@@ -28,6 +28,18 @@ import java.io.File
 import java.util.Date
 import java.util.concurrent.ScheduledExecutorService
 
+/**
+ * Records a rolling `errorReplayDuration` window: segments are encoded but held in memory, and
+ * frames and segments older than the window are dropped on every screenshot. Used when the session
+ * is not sampled by `sessionSampleRate` but `onErrorSampleRate` is set.
+ *
+ * Nothing is sent until [captureReplay] flushes the buffer for an error — sampled per error against
+ * `onErrorSampleRate`, unlike session mode which samples once at start. After a successful flush
+ * [convert] hands over to a [SessionCaptureStrategy] so the rest of the session is recorded live.
+ *
+ * Since nothing is in flight, `ReplayIntegration` deliberately keeps this strategy recording while
+ * rate-limited, so the buffer stays warm for when the limit expires.
+ */
 @SuppressLint("UseRequiresApi")
 @TargetApi(26)
 internal class BufferCaptureStrategy(

sentry-android-replay/src/main/java/io/sentry/android/replay/capture/SessionCaptureStrategy.kt

@@ -16,6 +16,17 @@ import io.sentry.util.FileUtils
 import java.util.Date
 import java.util.concurrent.ScheduledExecutorService
 
+/**
+ * Records a full session: segments are encoded and sent continuously, one per
+ * `sessionSegmentDuration`, until the 1h `sessionDuration` deadline. Used when the session is
+ * sampled by `sessionSampleRate`.
+ *
+ * [captureReplay] is a no-op here — there is no buffer to flush, the segment covering the error is
+ * sent like any other. Because envelopes are in flight the whole time, `ReplayIntegration` pauses
+ * this strategy while offline or rate-limited so the envelope cache doesn't overflow.
+ *
+ * See [BufferCaptureStrategy] for the on-error counterpart.
+ */
 internal class SessionCaptureStrategy(
   private val options: SentryOptions,
   private val scopes: IScopes?,