From ae127be736e2f8efac8d4732a4fee0c37167cfda Mon Sep 17 00:00:00 2001
From: valere <valeref@matrix.org>
Date: Fri, 7 Jul 2023 09:34:06 +0200
Subject: [PATCH] add documentation

---
 src/crypto-api/keybackup.ts | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/src/crypto-api/keybackup.ts b/src/crypto-api/keybackup.ts
index 30de43a603f..a7d474bd4ed 100644
--- a/src/crypto-api/keybackup.ts
+++ b/src/crypto-api/keybackup.ts
@@ -44,11 +44,20 @@ export interface KeyBackupInfo {
     version?: string; // number contained within
 }
 
+/**
+ * Status of the active key backup.
+ */
 export interface KeyBackupStatus {
+    /** The backup version */
     version: string;
+    /** True if the client is backing up keys to this backup */
     enabled: boolean;
 }
 
+/**
+ * Detailed signature information of a backup.
+ * This can be used to display what devices/identities are trusting a backup.
+ */
 export type SigInfo = {
     deviceId: string;
     valid?: boolean | null; // true: valid, false: invalid, null: cannot attempt validation
@@ -57,21 +66,40 @@ export type SigInfo = {
     deviceTrust?: DeviceTrustLevel;
 };
 
+/**
+ * Backup trust information.
+ * Client can upload and download from backup if `usable` is true.
+ */
 export type TrustInfo = {
     usable: boolean; // is the backup trusted, true iff there is a sig that is valid & from a trusted device
     sigs: SigInfo[];
     // eslint-disable-next-line camelcase
-    trusted_locally?: boolean;
+    trusted_locally?: boolean; // true if the private key is known. Notice that this is not enough to use the backup.
 };
 
+/**
+ * Active key backup info, if any.
+ * Returned as a result of `checkAndStart()`.
+ */
 export interface IKeyBackupCheck {
     backupInfo?: IKeyBackupInfo;
     trustInfo: TrustInfo;
 }
 
+/**
+ * Server side keys backup management.
+ * Devices may upload encrypted copies of keys to the server.
+ * When a device tries to read a message that it does not have keys for, it may request the key from the server and decrypt it.
+ */
 export interface SecureKeyBackup {
+    /**
+     * Gets the status of the current active key backup if any.
+     */
     getKeyBackupStatus(): Promise<KeyBackupStatus | null>;
 
+    /**
+     * Stop the SecureKeyBackup manager from backing up keys and allow a clean shutdown.
+     */
     stop(): void;
 
     /**