From caf841c53ea676c98bc4443b268a9e79d1408675 Mon Sep 17 00:00:00 2001
From: "Alexander \"PapaTutuWawa" <papatutuwawa@polynom.me>
Date: Mon, 26 Dec 2022 13:21:47 +0100
Subject: [PATCH] feat: Add more documentation

---
 lib/src/omemo/omemomanager.dart | 19 +++++++++++++++----
 lib/src/omemo/stanza.dart       | 16 ++++++++++++++++
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/lib/src/omemo/omemomanager.dart b/lib/src/omemo/omemomanager.dart
index ff4f30b..dbf9591 100644
--- a/lib/src/omemo/omemomanager.dart
+++ b/lib/src/omemo/omemomanager.dart
@@ -42,8 +42,14 @@ class OmemoManager {
   final Logger _log = Logger('OmemoManager');
 
   /// Functions for connecting with the OMEMO library
+
+  /// Send an empty OMEMO:2 message using the encrypted payload [result] to [recipientJid].
   final Future<void> Function(EncryptionResult result, String recipientJid) sendEmptyOmemoMessage;
+
+  /// Fetch the list of device ids associated with [jid].
   final Future<List<int>> Function(String jid) fetchDeviceList;
+
+  /// Fetch the device bundle for the device with id [id] of [jid]. If it cannot be fetched, return null.
   final Future<OmemoBundle?> Function(String jid, int id) fetchDeviceBundle;
   
   /// Map bare JID to its known devices
@@ -588,11 +594,16 @@ class OmemoManager {
   Future<void> ratchetAcknowledged(String jid, int deviceId, { bool enterCriticalSection = true }) async {
     if (enterCriticalSection) await _enterRatchetCriticalSection(jid);
 
-    final ratchet = _ratchetMap[RatchetMapKey(jid, deviceId)]!
-      ..acknowledged = true;
+    final key = RatchetMapKey(jid, deviceId);
+    if (_ratchetMap.containsKey(key)) {
+      final ratchet = _ratchetMap[key]!
+        ..acknowledged = true;
 
-    // Commit it
-    _eventStreamController.add(RatchetModifiedEvent(jid, deviceId, ratchet, false));
+      // Commit it
+      _eventStreamController.add(RatchetModifiedEvent(jid, deviceId, ratchet, false));
+    } else {
+      _log.severe('Attempted to acknowledge ratchet ${key.toJsonKey()}, even though it does not exist');
+    }
 
     if (enterCriticalSection) await _leaveRatchetCriticalSection(jid);
   }
diff --git a/lib/src/omemo/stanza.dart b/lib/src/omemo/stanza.dart
index 92f9f80..9ed4149 100644
--- a/lib/src/omemo/stanza.dart
+++ b/lib/src/omemo/stanza.dart
@@ -1,5 +1,6 @@
 import 'package:omemo_dart/src/omemo/encrypted_key.dart';
 
+/// Describes a stanza that was received by the underlying XMPP library.
 class OmemoIncomingStanza {
   const OmemoIncomingStanza(
     this.bareSenderJid,
@@ -8,18 +9,33 @@ class OmemoIncomingStanza {
     this.keys,
     this.payload,
   );
+
+  /// The bare JID of the sender of the stanza.
   final String bareSenderJid;
+
+  /// The device ID of the sender.
   final int senderDeviceId;
+
+  /// The timestamp when the stanza was received.
   final int timestamp;
+
+  /// The included encrypted keys
   final List<EncryptedKey> keys;
+
+  /// The string payload included in the <encrypted /> element.
   final String payload;
 }
 
+/// Describes a stanza that is to be sent out
 class OmemoOutgoingStanza {
   const OmemoOutgoingStanza(
     this.recipientJids,
     this.payload,
   );
+
+  /// The JIDs the stanza will be sent to.
   final List<String> recipientJids;
+
+  /// The serialised XML data that should be encrypted.
   final String payload;
 }