docs(backup): add documentation and samples [WPB-10575]

backup/README.md

@@ -3,6 +3,17 @@
 This module implements the Wire Cross-platform Backup solution.
 Its purpose is to create a common implementation to be used by iOS, Web, and Android.
 
+## Samples
+
+If you want to jump straight to examples, checkout the `nonJs` and `js` versions in the documentation:
+- [Importing](https://wireapp.github.io/kalium/backup/com.wire.backup.ingest/-m-p-backup-importer/index.html)
+- [Exporting](https://wireapp.github.io/kalium/backup/com.wire.backup.dump/-m-p-backup-exporter/index.html)
+
+## Data structure
+
+To see the currently supported data (conversations, users, messages, etc.), check
+[BackupData](https://wireapp.github.io/kalium/backup/com.wire.backup.data/-backup-message/index.html)
+
 ## Capabilities
 
 > [!TIP]

backup/build.gradle.kts

@@ -37,7 +37,6 @@ android {
     }
 }
 
-@Suppress("UnusedPrivateProperty")
 kotlin {
     // Makes visibility modifiers mandatory
     // Useful for a library that will be called by other clients

backup/src/commonMain/kotlin/com/wire/backup/dump/MPBackupExporter.kt

@@ -207,4 +207,8 @@ public abstract class CommonMPBackupExporter(
     }
 }
 
+/**
+ * Entity able to serialize [BackupData] entities, like [BackupMessage], [BackupConversation], [BackupUser]
+ * into a cross-platform [BackupData] format.
+ */
 public expect class MPBackupExporter : CommonMPBackupExporter

backup/src/commonMain/kotlin/com/wire/backup/ingest/MPBackupImporter.kt

@@ -157,4 +157,9 @@ public abstract class CommonMPBackupImporter internal constructor(
     internal abstract suspend fun unzipAllEntries(): BackupPageStorage
 }
 
+/**
+ * Entity able to parse backed-up data and returns
+ * digestible data in [BackupData] format.
+ * @sample samples.backup.BackupSample.commonImport
+ */
 public expect class MPBackupImporter : CommonMPBackupImporter

backup/src/jsMain/kotlin/com/wire/backup/dump/MPBackupExporter.kt

@@ -17,10 +17,14 @@
  */
 package com.wire.backup.dump
 
+import com.wire.backup.data.BackupConversation
+import com.wire.backup.data.BackupMessage
 import com.wire.backup.data.BackupQualifiedId
+import com.wire.backup.data.BackupUser
 import com.wire.backup.filesystem.BackupPage
 import com.wire.backup.filesystem.BackupPageStorage
 import com.wire.backup.filesystem.InMemoryBackupPageStorage
+import com.wire.kalium.protobuf.backup.BackupData
 import ext.libsodium.com.ionspin.kotlin.crypto.toUByteArray
 import ext.libsodium.com.ionspin.kotlin.crypto.toUInt8Array
 import kotlinx.coroutines.Deferred
@@ -32,6 +36,11 @@ import okio.Source
 import okio.buffer
 import kotlin.js.Promise
 
+/**
+ * Entity able to serialize [BackupData] entities, like [BackupMessage], [BackupConversation], [BackupUser]
+ * into a cross-platform [BackupData] format.
+ * @sample samples.backup.BackupSamplesJs.exportBackup
+ */
 @JsExport
 public actual class MPBackupExporter(
     selfUserId: BackupQualifiedId

backup/src/jsMain/kotlin/com/wire/backup/ingest/MPBackupImporter.kt

@@ -17,6 +17,7 @@
  */
 package com.wire.backup.ingest
 
+import com.wire.backup.data.BackupData
 import com.wire.backup.dump.JSZip
 import com.wire.backup.filesystem.BackupPage
 import com.wire.backup.filesystem.BackupPageStorage
@@ -31,6 +32,12 @@ import okio.Sink
 import org.khronos.webgl.Uint8Array
 import kotlin.js.Promise
 
+/**
+ * Entity able to parse backed-up data and returns
+ * digestible data in [BackupData] format.
+ * @sample samples.backup.BackupSamplesJs.peekBackup
+ * @sample samples.backup.BackupSamples.commonImport
+ */
 @JsExport
 public actual class MPBackupImporter : CommonMPBackupImporter() {
     private val inMemoryUnencryptedBuffer = Buffer()

backup/src/nonJsMain/kotlin/com/wire/backup/dump/MPBackupExporter.kt

@@ -18,17 +18,26 @@
 package com.wire.backup.dump
 
 import com.rickclephas.kmp.nativecoroutines.NativeCoroutines
+import com.wire.backup.data.BackupConversation
+import com.wire.backup.data.BackupMessage
 import com.wire.backup.data.BackupQualifiedId
+import com.wire.backup.data.BackupUser
 import com.wire.backup.filesystem.BackupPage
 import com.wire.backup.filesystem.BackupPageStorage
 import com.wire.backup.filesystem.FileBasedBackupPageStorage
+import com.wire.kalium.protobuf.backup.BackupData
 import kotlinx.coroutines.CompletableDeferred
 import kotlinx.coroutines.Deferred
 import okio.FileSystem
 import okio.Path.Companion.toPath
 import okio.SYSTEM
 import okio.Source
 
+/**
+ * Entity able to serialize [BackupData] entities, like [BackupMessage], [BackupConversation], [BackupUser]
+ * into a cross-platform [BackupData] format.
+ * @sample samples.backup.BackupSamplesNonJS.exportBackup
+ */
 public actual class MPBackupExporter(
     selfUserId: BackupQualifiedId,
     workDirectory: String,

backup/src/nonJsMain/kotlin/com/wire/backup/ingest/BackupFileUnzipper.kt

@@ -17,7 +17,7 @@
  */
 package com.wire.backup.ingest
 
-public interface BackupFileUnzipper {
+public fun interface BackupFileUnzipper {
 
     /**
      * Unzip all the entries stored within the file at [zipPath] to _some_ directory of choice.

backup/src/nonJsMain/kotlin/com/wire/backup/ingest/MPBackupImporter.kt

@@ -18,6 +18,7 @@
 package com.wire.backup.ingest
 
 import com.rickclephas.kmp.nativecoroutines.NativeCoroutines
+import com.wire.backup.data.BackupData
 import com.wire.backup.filesystem.BackupPageStorage
 import com.wire.backup.filesystem.FileBasedBackupPageStorage
 import okio.FileSystem
@@ -28,6 +29,12 @@ import okio.Sink
 import kotlin.experimental.ExperimentalObjCName
 import kotlin.native.ObjCName
 
+/**
+ * Entity able to parse backed-up data and returns
+ * digestible data in [BackupData] format.
+ * @sample samples.backup.BackupSamplesNonJS.peekBackup
+ * @sample samples.backup.BackupSamples.commonImport
+ */
 @OptIn(ExperimentalObjCName::class)
 public actual class MPBackupImporter(
     private val pathToWorkDirectory: String,

buildSrc/src/main/kotlin/com/wire/kalium/plugins/CommonDokkaConfig.kt

@@ -23,6 +23,7 @@ import org.jetbrains.dokka.DokkaConfiguration.Visibility
 import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
 
 val documentedSubprojects = listOf(
+    "backup",
     "calling",
     "cli",
     "cryptography",

data/build.gradle.kts

@@ -27,7 +27,6 @@ kaliumLibrary {
     multiplatform { }
 }
 
-@Suppress("UnusedPrivateProperty")
 kotlin {
     sourceSets {
         val commonMain by getting {