From 4ed2d3dec3f7ab2101a670a9b2ab009779af5d11 Mon Sep 17 00:00:00 2001
From: "Alexander \"PapaTutuWawa" <papatutuwawa@polynom.me>
Date: Thu, 15 Jun 2023 22:46:37 +0200
Subject: [PATCH] docs: Improve docstrings

---
 lib/src/omemo/encrypted_key.dart | 15 +++++++++++++--
 lib/src/omemo/omemo.dart         | 18 ++++++++----------
 2 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/lib/src/omemo/encrypted_key.dart b/lib/src/omemo/encrypted_key.dart
index d1fc4f3..2e1e1eb 100644
--- a/lib/src/omemo/encrypted_key.dart
+++ b/lib/src/omemo/encrypted_key.dart
@@ -1,12 +1,23 @@
+import 'dart:convert';
+
 import 'package:meta/meta.dart';
 
 /// EncryptedKey is the intermediary format of a <key /> element in the OMEMO message's
 /// <keys /> header.
 @immutable
 class EncryptedKey {
-  const EncryptedKey(this.jid, this.rid, this.value, this.kex);
-  final String jid;
+  const EncryptedKey(this.rid, this.value, this.kex);
+
+  /// The id of the device the key is encrypted for.
   final int rid;
+
+  /// The base64-encoded payload.
   final String value;
+
+  /// Flag indicating whether the payload is a OMEMOKeyExchange (true) or
+  /// an OMEMOAuthenticatedMessage (false).
   final bool kex;
+
+  /// The base64-decoded payload.
+  List<int> get data => base64Decode(value);
 }
diff --git a/lib/src/omemo/omemo.dart b/lib/src/omemo/omemo.dart
index dff324f..34c226a 100644
--- a/lib/src/omemo/omemo.dart
+++ b/lib/src/omemo/omemo.dart
@@ -28,6 +28,7 @@ import 'package:omemo_dart/src/x3dh/x3dh.dart';
 import 'package:synchronized/synchronized.dart';
 
 extension AppendToListOrCreateExtension<K, V> on Map<K, List<V>> {
+  /// Create or append [value] to the list identified with key [key].
   void appendOrCreate(K key, V value) {
     if (containsKey(key)) {
       this[key]!.add(value);
@@ -38,6 +39,8 @@ extension AppendToListOrCreateExtension<K, V> on Map<K, List<V>> {
 }
 
 extension StringFromBase64Extension on String {
+  /// Base64-decode this string. Useful for doing `someString?.fromBase64()` instead
+  /// of `someString != null ? base64Decode(someString) : null`.
   List<int> fromBase64() => base64Decode(this);
 }
 
@@ -255,7 +258,7 @@ class OmemoManager {
     var processAsKex = key.kex;
     if (key.kex && _ratchetMap.containsKey(ratchetKey)) {
       final ratchet = _ratchetMap[ratchetKey]!;
-      final kexMessage = OMEMOKeyExchange.fromBuffer(base64Decode(key.value));
+      final kexMessage = OMEMOKeyExchange.fromBuffer(key.data);
       final ratchetEk = await ratchet.kex.ek.getBytes();
       final sameEk = listsEqual(kexMessage.ek, ratchetEk);
 
@@ -270,7 +273,7 @@ class OmemoManager {
     // Process the message
     if (processAsKex) {
       _log.finest('Decoding message as OMEMOKeyExchange');
-      final kexMessage = OMEMOKeyExchange.fromBuffer(base64Decode(key.value));
+      final kexMessage = OMEMOKeyExchange.fromBuffer(key.data);
 
       // Find the correct SPK
       final device = await getDevice();
@@ -327,7 +330,7 @@ class OmemoManager {
       }
 
       final result = await _decryptAndVerifyHmac(
-        stanza.payload != null ? base64Decode(stanza.payload!) : null,
+        stanza.payload?.fromBase64(),
         keyAndHmac.get<List<int>>(),
       );
       if (result.isType<OmemoError>()) {
@@ -414,11 +417,9 @@ class OmemoManager {
         _log.finest(
           'Extracting OMEMOAuthenticatedMessage from OMEMOKeyExchange',
         );
-        authMessage =
-            OMEMOKeyExchange.fromBuffer(base64Decode(key.value)).message;
+        authMessage = OMEMOKeyExchange.fromBuffer(key.data).message;
       } else {
-        authMessage =
-            OMEMOAuthenticatedMessage.fromBuffer(base64Decode(key.value));
+        authMessage = OMEMOAuthenticatedMessage.fromBuffer(key.data);
       }
 
       final keyAndHmac = await ratchet.ratchetDecrypt(authMessage);
@@ -632,7 +633,6 @@ class OmemoManager {
           encryptedKeys.appendOrCreate(
             jid,
             EncryptedKey(
-              jid,
               device,
               base64Encode(kexMessage.writeToBuffer()),
               true,
@@ -652,7 +652,6 @@ class OmemoManager {
           encryptedKeys.appendOrCreate(
             jid,
             EncryptedKey(
-              jid,
               device,
               base64Encode(kexMessage.writeToBuffer()),
               true,
@@ -663,7 +662,6 @@ class OmemoManager {
           encryptedKeys.appendOrCreate(
             jid,
             EncryptedKey(
-              jid,
               device,
               base64Encode(authMessage.writeToBuffer()),
               false,