From c4c7dac9cf8d9c66535c67dc1ae1cbf6e551f5f7 Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoit@matrix.org>
Date: Fri, 14 Aug 2026 11:48:59 +0200
Subject: [PATCH] Add KDoc to the `features/rageshake` API interfaces

Document RageshakeFeatureAvailability, LogFilesRemover and the BugReporter
interface, and complete the docs of its remaining members.

The BugReporter doc records that progress and the outcome arrive through the
listener passed to sendBugReport rather than through a return value or an
exception.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../rageshake/api/RageshakeFeatureAvailability.kt   |  4 ++++
 .../features/rageshake/api/logs/LogFilesRemover.kt  |  3 +++
 .../features/rageshake/api/reporter/BugReporter.kt  | 13 +++++++++++--
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/features/rageshake/api/src/main/kotlin/io/element/android/features/rageshake/api/RageshakeFeatureAvailability.kt b/features/rageshake/api/src/main/kotlin/io/element/android/features/rageshake/api/RageshakeFeatureAvailability.kt
index bc72e7021b..c4205c1575 100644
--- a/features/rageshake/api/src/main/kotlin/io/element/android/features/rageshake/api/RageshakeFeatureAvailability.kt
+++ b/features/rageshake/api/src/main/kotlin/io/element/android/features/rageshake/api/RageshakeFeatureAvailability.kt
@@ -10,6 +10,10 @@ package io.element.android.features.rageshake.api
 
 import kotlinx.coroutines.flow.Flow
 
+/**
+ * Tells whether bug reporting is available, which an enterprise deployment can turn off.
+ */
 fun interface RageshakeFeatureAvailability {
+    /** Whether the rageshake and bug report entry points should be offered to the user. */
     fun isAvailable(): Flow<Boolean>
 }
diff --git a/features/rageshake/api/src/main/kotlin/io/element/android/features/rageshake/api/logs/LogFilesRemover.kt b/features/rageshake/api/src/main/kotlin/io/element/android/features/rageshake/api/logs/LogFilesRemover.kt
index f8eee31675..a7b2961ab6 100644
--- a/features/rageshake/api/src/main/kotlin/io/element/android/features/rageshake/api/logs/LogFilesRemover.kt
+++ b/features/rageshake/api/src/main/kotlin/io/element/android/features/rageshake/api/logs/LogFilesRemover.kt
@@ -10,6 +10,9 @@ package io.element.android.features.rageshake.api.logs
 
 import java.io.File
 
+/**
+ * Deletes the log files the app writes, used to keep them from growing without bound and to clear them on request.
+ */
 interface LogFilesRemover {
     /**
      * Perform the log files removal.
diff --git a/features/rageshake/api/src/main/kotlin/io/element/android/features/rageshake/api/reporter/BugReporter.kt b/features/rageshake/api/src/main/kotlin/io/element/android/features/rageshake/api/reporter/BugReporter.kt
index 631a51a686..c1611f30b5 100644
--- a/features/rageshake/api/src/main/kotlin/io/element/android/features/rageshake/api/reporter/BugReporter.kt
+++ b/features/rageshake/api/src/main/kotlin/io/element/android/features/rageshake/api/reporter/BugReporter.kt
@@ -10,6 +10,11 @@ package io.element.android.features.rageshake.api.reporter
 
 import java.io.File
 
+/**
+ * Uploads bug reports, including the log files the app has been writing.
+ *
+ * Progress and the outcome are reported through the listener passed to [sendBugReport] rather than by returning or throwing.
+ */
 interface BugReporter {
     /**
      * Send a bug report.
@@ -35,17 +40,21 @@ interface BugReporter {
     )
 
     /**
-     * Provide the log directory.
+     * Provide the log directory, i.e. where the rotating log files are written.
      */
     fun logDirectory(): File
 
     /**
-     * Set the current tracing log level.
+     * Set the current tracing log level, so it can be reported alongside the bug.
+     *
+     * @param logLevel the log level currently in effect.
      */
     fun setCurrentTracingLogLevel(logLevel: String)
 
     /**
      * Save the logcat.
+     *
+     * @return the file the logcat was written to, or `null` when it could not be captured.
      */
     fun saveLogCat(): File?
 }