diff --git a/smack-omemo-signal/src/main/java/org/jivesoftware/smackx/omemo/signal/SignalCachingOmemoStore.java b/smack-omemo-signal/src/main/java/org/jivesoftware/smackx/omemo/signal/SignalCachingOmemoStore.java
index 084d95f2b..135bd96fb 100644
--- a/smack-omemo-signal/src/main/java/org/jivesoftware/smackx/omemo/signal/SignalCachingOmemoStore.java
+++ b/smack-omemo-signal/src/main/java/org/jivesoftware/smackx/omemo/signal/SignalCachingOmemoStore.java
@@ -44,6 +44,7 @@ public class SignalCachingOmemoStore extends CachingOmemoStore<IdentityKeyPair,
     /**
      * Create a new SignalCachingOmemoStore as a caching layer around a persisting OmemoStore
      * (eg. a SignalFileBasedOmemoStore).
+     *
      * @param wrappedStore other store implementation that gets wrapped
      */
     public SignalCachingOmemoStore(OmemoStore<IdentityKeyPair, IdentityKey, PreKeyRecord, SignedPreKeyRecord,
diff --git a/smack-omemo-signal/src/main/java/org/jivesoftware/smackx/omemo/signal/SignalOmemoRatchet.java b/smack-omemo-signal/src/main/java/org/jivesoftware/smackx/omemo/signal/SignalOmemoRatchet.java
index c219b6f14..6ab4311f8 100644
--- a/smack-omemo-signal/src/main/java/org/jivesoftware/smackx/omemo/signal/SignalOmemoRatchet.java
+++ b/smack-omemo-signal/src/main/java/org/jivesoftware/smackx/omemo/signal/SignalOmemoRatchet.java
@@ -149,7 +149,6 @@ public class SignalOmemoRatchet
             throw new AssertionError("Signals trust management MUST be disabled.");
         }
 
-        // TODO: Figure out, if this is enough...
         int type = ciphertextMessage.getType() == CiphertextMessage.PREKEY_TYPE ?
                 OmemoElement.TYPE_OMEMO_PREKEY_MESSAGE : OmemoElement.TYPE_OMEMO_MESSAGE;
 
diff --git a/smack-omemo-signal/src/main/java/org/jivesoftware/smackx/omemo/signal/SignalOmemoStoreConnector.java b/smack-omemo-signal/src/main/java/org/jivesoftware/smackx/omemo/signal/SignalOmemoStoreConnector.java
index 751dcc830..69b43927c 100644
--- a/smack-omemo-signal/src/main/java/org/jivesoftware/smackx/omemo/signal/SignalOmemoStoreConnector.java
+++ b/smack-omemo-signal/src/main/java/org/jivesoftware/smackx/omemo/signal/SignalOmemoStoreConnector.java
@@ -87,8 +87,9 @@ public class SignalOmemoStoreConnector
     }
 
     /**
-     * We don't use this.
-     * @return dummy TODO javadoc me please
+     * The OMEMO protocol does not make use of a local registration ID, so we can simply return 0 here.
+     *
+     * @return local registration id.
      */
     @Override
     public int getLocalRegistrationId() {
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/CachingOmemoStore.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/CachingOmemoStore.java
index d2fd9966b..766141b5c 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/CachingOmemoStore.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/CachingOmemoStore.java
@@ -75,7 +75,13 @@ public class CachingOmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_Se
         if (persistent != null) {
             return persistent.localDeviceIdsOf(localUser);
         } else {
-            return new TreeSet<>(); //TODO: ?
+            SortedSet<Integer> deviceIds = new TreeSet<>();
+            for (OmemoDevice device : caches.keySet()) {
+                if (device.getJid().equals(localUser)) {
+                    deviceIds.add(device.getDeviceId());
+                }
+            }
+            return deviceIds;
         }
     }
 
@@ -437,8 +443,9 @@ public class CachingOmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_Se
 
     /**
      * Return the {@link KeyCache} object of an {@link OmemoManager}.
-     * @param device TODO javadoc me please
-     * @return
+     *
+     * @param device OMEMO device of which we want to have the cache.
+     * @return key cache of the device
      */
     private KeyCache<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_Sess> getCache(OmemoDevice device) {
         KeyCache<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_Sess> cache = caches.get(device);
@@ -451,11 +458,12 @@ public class CachingOmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_Se
 
     /**
      * Cache that stores values for an {@link OmemoManager}.
-     * @param <T_IdKeyPair>
-     * @param <T_IdKey>
-     * @param <T_PreKey>
-     * @param <T_SigPreKey>
-     * @param <T_Sess>
+     *
+     * @param <T_IdKeyPair> type of the identity key pair
+     * @param <T_IdKey> type of the public identity key
+     * @param <T_PreKey> type of a public preKey
+     * @param <T_SigPreKey> type of the public signed preKey
+     * @param <T_Sess> type of the OMEMO session
      */
     private static class KeyCache<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_Sess> {
         private T_IdKeyPair identityKeyPair;
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/FileBasedOmemoStore.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/FileBasedOmemoStore.java
index d8b1df42c..62b742db5 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/FileBasedOmemoStore.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/FileBasedOmemoStore.java
@@ -45,6 +45,7 @@ import org.jxmpp.jid.BareJid;
 
 /**
  * Like a rocket!
+ * Implementation of the {@link OmemoStore} class that uses plain files for storage.
  *
  * @author Paul Schaub
  */
@@ -514,7 +515,7 @@ public abstract class FileBasedOmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigP
 
     /**
      * Delete a directory with all subdirectories.
-     * @param root TODO javadoc me please
+     * @param root directory to be deleted
      */
     public static void deleteDirectory(File root) {
         File[] currList;
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoConfiguration.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoConfiguration.java
index c53f97dac..aa91b7ce5 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoConfiguration.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoConfiguration.java
@@ -30,7 +30,7 @@ public final class OmemoConfiguration {
      * Set to true, in order to ignore read-only devices.
      *
      * @param ignore ignore read-only devices
-     * @see <a href="example.com">Blog Post explaining the danger of read-only devices. TODO: Add URL </a>
+     * @see <a href="https://blog.jabberhead.tk/2019/12/13/pitfalls-for-omemo-implementations-part-1-inactive-devices/">Blog Post explaining the danger of read-only devices.</a>
      */
     public static void setIgnoreReadOnlyDevices(boolean ignore) {
         IGNORE_READ_ONLY_DEVICES = ignore;
@@ -40,7 +40,7 @@ public final class OmemoConfiguration {
      * Return true, if the client should stop encrypting messages to a read-only device.
      *
      * @return true if read-only devices should get ignored after a certain amount of unanswered messages.
-     * @see <a href="example.com">Blog Post explaining the danger of read-only devices. TODO: Add URL </a>
+     * @see <a href="https://blog.jabberhead.tk/2019/12/13/pitfalls-for-omemo-implementations-part-1-inactive-devices/">Blog Post explaining the danger of read-only devices.</a>
      */
     public static boolean getIgnoreReadOnlyDevices() {
         return IGNORE_READ_ONLY_DEVICES;
@@ -53,7 +53,7 @@ public final class OmemoConfiguration {
      * This threshold is used to prevent read-only devices from weakening forward secrecy.
      *
      * @param maxReadOnlyMessageCount maximum number of allowed messages to a read-only device.
-     * @see <a href="example.com">Blog Post explaining the danger of read-only devices. TODO: Add URL </a>
+     * @see <a href="https://blog.jabberhead.tk/2019/12/13/pitfalls-for-omemo-implementations-part-1-inactive-devices/">Blog Post explaining the danger of read-only devices.</a>
      */
     public static void setMaxReadOnlyMessageCount(int maxReadOnlyMessageCount) {
         if (maxReadOnlyMessageCount <= 0) {
@@ -69,7 +69,7 @@ public final class OmemoConfiguration {
      * This threshold is used to prevent read-only devices from weakening forward secrecy.
      *
      * @return maximum number of allowed messages to a read-only device.
-     * @see <a href="example.com">Blog Post explaining the danger of read-only devices. TODO: Add URL </a>
+     * @see <a href="https://blog.jabberhead.tk/2019/12/13/pitfalls-for-omemo-implementations-part-1-inactive-devices/">Blog Post explaining the danger of read-only devices.</a>
      */
     public static int getMaxReadOnlyMessageCount() {
         return MAX_READ_ONLY_MESSAGE_COUNT;
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoInitializer.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoInitializer.java
index 5f293490f..a5d1836ad 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoInitializer.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoInitializer.java
@@ -19,7 +19,7 @@ package org.jivesoftware.smackx.omemo;
 import org.jivesoftware.smack.initializer.UrlInitializer;
 
 /**
- * Initializer class that registers omemo providers.
+ * Initializer class that registers OMEMO providers.
  *
  * @author Paul Schaub
  */
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoManager.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoManager.java
index a3d2ff48d..c319df84d 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoManager.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoManager.java
@@ -151,7 +151,7 @@ public final class OmemoManager extends Manager {
      * @param connection XmppConnection.
      * @param deviceId MUST NOT be null and MUST be greater than 0.
      *
-     * @return manager TODO javadoc me please
+     * @return OmemoManager instance for the given connection and deviceId.
      */
     public static synchronized OmemoManager getInstanceFor(XMPPConnection connection, Integer deviceId) {
         if (deviceId == null || deviceId < 1) {
@@ -182,7 +182,7 @@ public final class OmemoManager extends Manager {
      *
      * @param connection XmppConnection.
      *
-     * @return manager TODO javadoc me please
+     * @return OmemoManager instance for the given connection and a determined deviceId.
      */
     public static synchronized OmemoManager getInstanceFor(XMPPConnection connection) {
         TreeMap<Integer, OmemoManager> managers = INSTANCES.get(connection);
@@ -219,7 +219,8 @@ public final class OmemoManager extends Manager {
 
     /**
      * Return the TrustCallback of this manager.
-     * @return
+     *
+     * @return callback that is used for trust decisions.
      */
     OmemoTrustCallback getTrustCallback() {
         return trustCallback;
@@ -276,9 +277,12 @@ public final class OmemoManager extends Manager {
     /**
      * Return a set of all OMEMO capable devices of a contact.
      * Note, that this method does not explicitly refresh the device list of the contact, so it might be outdated.
+     *
      * @see #requestDeviceListUpdateFor(BareJid)
+     *
      * @param contact contact we want to get a set of device of.
      * @return set of known devices of that contact.
+     *
      * @throws IOException if an I/O error occurred.
      */
     public Set<OmemoDevice> getDevicesOf(BareJid contact) throws IOException {
@@ -299,6 +303,7 @@ public final class OmemoManager extends Manager {
      * @param recipient recipients bareJid
      * @param message text to encrypt
      * @return encrypted message
+     *
      * @throws CryptoFailedException                when something crypto related fails
      * @throws UndecidedOmemoIdentityException      When there are undecided devices
      * @throws InterruptedException if the calling thread was interrupted.
@@ -311,9 +316,9 @@ public final class OmemoManager extends Manager {
             throws CryptoFailedException, UndecidedOmemoIdentityException,
             InterruptedException, SmackException.NotConnectedException,
             SmackException.NoResponseException, SmackException.NotLoggedInException, IOException {
-            Set<BareJid> recipients = new HashSet<>();
-            recipients.add(recipient);
-            return encrypt(recipients, message);
+        Set<BareJid> recipients = new HashSet<>();
+        recipients.add(recipient);
+        return encrypt(recipients, message);
     }
 
     /**
@@ -322,6 +327,7 @@ public final class OmemoManager extends Manager {
      * @param recipients recipients barejids
      * @param message text to encrypt
      * @return encrypted message.
+     *
      * @throws CryptoFailedException    When something crypto related fails
      * @throws UndecidedOmemoIdentityException  When there are undecided devices.
      * @throws InterruptedException if the calling thread was interrupted.
@@ -348,6 +354,7 @@ public final class OmemoManager extends Manager {
      * @param muc multiUserChat
      * @param message message to send
      * @return encrypted message
+     *
      * @throws UndecidedOmemoIdentityException when there are undecided devices.
      * @throws CryptoFailedException if the OMEMO cryptography failed.
      * @throws XMPPException.XMPPErrorException if there was an XMPP error returned.
@@ -402,6 +409,7 @@ public final class OmemoManager extends Manager {
      *
      * @param mamQuery The MAM query
      * @return list of decrypted OmemoMessages
+     *
      * @throws SmackException.NotLoggedInException if the Manager is not authenticated.
      * @throws IOException if an I/O error occurred.
      */
@@ -430,6 +438,7 @@ public final class OmemoManager extends Manager {
      * Distrust the fingerprint/OmemoDevice tuple.
      * The fingerprint must be the lowercase, hexadecimal fingerprint of the identityKey of the device and must
      * be of length 64.
+     *
      * @param device device
      * @param fingerprint fingerprint
      */
@@ -445,6 +454,7 @@ public final class OmemoManager extends Manager {
      * Returns true, if the fingerprint/OmemoDevice tuple is trusted, otherwise false.
      * The fingerprint must be the lowercase, hexadecimal fingerprint of the identityKey of the device and must
      * be of length 64.
+     *
      * @param device device
      * @param fingerprint fingerprint
      * @return <code>true</code> if this is a trusted OMEMO identity.
@@ -461,6 +471,7 @@ public final class OmemoManager extends Manager {
      * Returns true, if the fingerprint/OmemoDevice tuple is decided by the user.
      * The fingerprint must be the lowercase, hexadecimal fingerprint of the identityKey of the device and must
      * be of length 64.
+     *
      * @param device device
      * @param fingerprint fingerprint
      * @return <code>true</code> if the trust is decided for the identity.
@@ -478,6 +489,7 @@ public final class OmemoManager extends Manager {
      * secrecy.
      *
      * @param recipient recipient
+     *
      * @throws CorruptedOmemoKeyException           When the used identityKeys are corrupted
      * @throws CryptoFailedException                When something fails with the crypto
      * @throws CannotEstablishOmemoSessionException When we can't establish a session with the recipient
@@ -494,8 +506,8 @@ public final class OmemoManager extends Manager {
             CryptoFailedException, CannotEstablishOmemoSessionException, IOException {
         XMPPConnection connection = connection();
         MessageBuilder message = connection.getStanzaFactory()
-                        .buildMessageStanza()
-                        .to(recipient.getJid());
+                .buildMessageStanza()
+                .to(recipient.getJid());
 
         OmemoElement element = getOmemoService().createRatchetUpdateElement(new LoggedInOmemoManager(this), recipient);
         message.addExtension(element);
@@ -510,6 +522,7 @@ public final class OmemoManager extends Manager {
      *
      * @param contact contact
      * @return true if contact has at least one OMEMO capable device.
+     *
      * @throws SmackException.NotConnectedException if the XMPP connection is not connected.
      * @throws InterruptedException if the calling thread was interrupted.
      * @throws SmackException.NoResponseException if there was no response from the remote entity.
@@ -530,10 +543,11 @@ public final class OmemoManager extends Manager {
      *
      * @param multiUserChat MUC
      * @return true if chat supports OMEMO
-     * @throws XMPPException.XMPPErrorException     if
-     * @throws SmackException.NotConnectedException something
-     * @throws InterruptedException                 goes
-     * @throws SmackException.NoResponseException   wrong
+     *
+     * @throws XMPPException.XMPPErrorException     if there was an XMPP protocol level error
+     * @throws SmackException.NotConnectedException if the connection is not connected
+     * @throws InterruptedException                 if the thread is interrupted
+     * @throws SmackException.NoResponseException   if the server does not respond
      */
     public boolean multiUserChatSupportsOmemo(MultiUserChat multiUserChat)
             throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException,
@@ -549,6 +563,7 @@ public final class OmemoManager extends Manager {
      * @param connection XMPPConnection
      * @param server domainBareJid of the server to test
      * @return true if server supports pep
+     *
      * @throws XMPPException.XMPPErrorException if there was an XMPP error returned.
      * @throws SmackException.NotConnectedException if the XMPP connection is not connected.
      * @throws InterruptedException if the calling thread was interrupted.
@@ -564,7 +579,8 @@ public final class OmemoManager extends Manager {
     /**
      * Return the fingerprint of our identity key.
      *
-     * @return fingerprint TODO javadoc me please
+     * @return our own OMEMO fingerprint
+     *
      * @throws SmackException.NotLoggedInException if we don't know our bareJid yet.
      * @throws CorruptedOmemoKeyException if our identityKey is corrupted.
      * @throws IOException if an I/O error occurred.
@@ -580,8 +596,10 @@ public final class OmemoManager extends Manager {
 
     /**
      * Get the fingerprint of a contacts device.
+     *
      * @param device contacts OmemoDevice
-     * @return fingerprint TODO javadoc me please
+     * @return fingerprint of the given OMEMO device.
+     *
      * @throws CannotEstablishOmemoSessionException if we have no session yet, and are unable to create one.
      * @throws SmackException.NotLoggedInException if the XMPP connection is not authenticated.
      * @throws CorruptedOmemoKeyException if the copy of the fingerprint we have is corrupted.
@@ -609,6 +627,7 @@ public final class OmemoManager extends Manager {
     /**
      * Return all OmemoFingerprints of active devices of a contact.
      * TODO: Make more fail-safe
+     *
      * @param contact contact
      * @return Map of all active devices of the contact and their fingerprints.
      *
@@ -656,6 +675,7 @@ public final class OmemoManager extends Manager {
 
     /**
      * Remove an OmemoMessageListener.
+     *
      * @param listener OmemoMessageListener
      */
     public void removeOmemoMessageListener(OmemoMessageListener listener) {
@@ -673,6 +693,7 @@ public final class OmemoManager extends Manager {
 
     /**
      * Remove an OmemoMucMessageListener.
+     *
      * @param listener OmemoMucMessageListener
      */
     public void removeOmemoMucMessageListener(OmemoMucMessageListener listener) {
@@ -683,6 +704,7 @@ public final class OmemoManager extends Manager {
      * Request a deviceList update from contact contact.
      *
      * @param contact contact we want to obtain the deviceList from.
+     *
      * @throws InterruptedException if the calling thread was interrupted.
      * @throws PubSubException.NotALeafNodeException if a PubSub leaf node operation was attempted on a non-leaf node.
      * @throws XMPPException.XMPPErrorException if there was an XMPP error returned.
@@ -729,8 +751,8 @@ public final class OmemoManager extends Manager {
      */
     public synchronized void rotateSignedPreKey()
             throws CorruptedOmemoKeyException, SmackException.NotLoggedInException, XMPPException.XMPPErrorException,
-                    SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException,
-                    IOException, PubSubException.NotALeafNodeException {
+            SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException,
+            IOException, PubSubException.NotALeafNodeException {
         if (!connection().isAuthenticated()) {
             throw new SmackException.NotLoggedInException();
         }
@@ -745,6 +767,7 @@ public final class OmemoManager extends Manager {
 
     /**
      * Return true, if the given Stanza contains an OMEMO element 'encrypted'.
+     *
      * @param stanza stanza
      * @return true if stanza has extension 'encrypted'
      */
@@ -763,7 +786,8 @@ public final class OmemoManager extends Manager {
 
     /**
      * Returns a pseudo random number from the interval [1, Integer.MAX_VALUE].
-     * @return deviceId TODO javadoc me please
+     *
+     * @return a random deviceId.
      */
     public static int randomDeviceId() {
         return new Random().nextInt(Integer.MAX_VALUE - 1) + 1;
@@ -772,7 +796,7 @@ public final class OmemoManager extends Manager {
     /**
      * Return the BareJid of the user.
      *
-     * @return bareJid TODO javadoc me please
+     * @return our own bare JID.
      */
     public BareJid getOwnJid() {
         if (ownJid == null && connection().isAuthenticated()) {
@@ -785,7 +809,7 @@ public final class OmemoManager extends Manager {
     /**
      * Return the deviceId of this OmemoManager.
      *
-     * @return deviceId TODO javadoc me please
+     * @return this OmemoManagers deviceId.
      */
     public synchronized Integer getDeviceId() {
         return deviceId;
@@ -794,7 +818,7 @@ public final class OmemoManager extends Manager {
     /**
      * Return the OmemoDevice of the user.
      *
-     * @return omemoDevice TODO javadoc me please
+     * @return our own OmemoDevice
      */
     public synchronized OmemoDevice getOwnDevice() {
         BareJid jid = getOwnJid();
@@ -806,6 +830,7 @@ public final class OmemoManager extends Manager {
 
     /**
      * Set the deviceId of the manager to nDeviceId.
+     *
      * @param nDeviceId new deviceId
      */
     synchronized void setDeviceId(int nDeviceId) {
@@ -926,7 +951,7 @@ public final class OmemoManager extends Manager {
     /**
      * Return the OMEMO service object.
      *
-     * @return omemoService TODO javadoc me please
+     * @return the OmemoService object related to this OmemoManager.
      */
     OmemoService<?, ?, ?, ?, ?, ?, ?, ?, ?> getOmemoService() {
         throwIfNoServiceSet();
@@ -1012,7 +1037,7 @@ public final class OmemoManager extends Manager {
                     OmemoDeviceListElement receivedDeviceList = (OmemoDeviceListElement) payloadItem.getPayload();
                     try {
                         getOmemoService().getOmemoStoreBackend().mergeCachedDeviceList(getOwnDevice(), from,
-                                        receivedDeviceList);
+                                receivedDeviceList);
 
                         if (!from.asBareJid().equals(getOwnJid())) {
                             continue;
@@ -1021,8 +1046,8 @@ public final class OmemoManager extends Manager {
                         deviceList = getOmemoService().cleanUpDeviceList(getOwnDevice());
                     } catch (IOException e) {
                         LOGGER.log(Level.SEVERE,
-                                        "IOException while processing OMEMO PEP device updates. Message: " + message,
-                                        e);
+                                "IOException while processing OMEMO PEP device updates. Message: " + message,
+                                e);
                         continue;
                     }
                     final OmemoDeviceListElement_VAxolotl newDeviceList = new OmemoDeviceListElement_VAxolotl(deviceList);
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoMessage.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoMessage.java
index 2d5554e7f..e2eb8635a 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoMessage.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoMessage.java
@@ -49,7 +49,7 @@ public class OmemoMessage {
     /**
      * Return the original OmemoElement (&lt;encrypted/&gt;).
      *
-     * @return omemoElement TODO javadoc me please
+     * @return omemoElement of the message
      */
     public OmemoElement getElement() {
         return element;
@@ -58,7 +58,7 @@ public class OmemoMessage {
     /**
      * Return the messageKey (or transported key in case of a KeyTransportMessage).
      *
-     * @return key TODO javadoc me please
+     * @return encryption key that protects the message payload
      */
     public byte[] getKey() {
         return messageKey.clone();
@@ -66,6 +66,7 @@ public class OmemoMessage {
 
     /**
      * Return the initialization vector belonging to the key.
+     *
      * @return initialization vector
      */
     public byte[] getIv() {
@@ -81,6 +82,7 @@ public class OmemoMessage {
 
         /**
          * Create a new outgoing OMEMO message.
+         *
          * @param element OmemoElement
          * @param key messageKey (or transported key)
          * @param iv initialization vector belonging to key
@@ -96,6 +98,7 @@ public class OmemoMessage {
 
         /**
          * Return a list of all devices the sender originally intended to encrypt the message for.
+         *
          * @return list of intended recipients.
          */
         public Set<OmemoDevice> getIntendedDevices() {
@@ -104,6 +107,7 @@ public class OmemoMessage {
 
         /**
          * Return a map of all skipped recipients and the reasons for skipping.
+         *
          * @return map of skipped recipients and reasons for that.
          */
         public HashMap<OmemoDevice, Throwable> getSkippedDevices() {
@@ -112,6 +116,7 @@ public class OmemoMessage {
 
         /**
          * Determine, if some recipients were skipped during encryption.
+         *
          * @return true if recipients were skipped.
          */
         public boolean isMissingRecipients() {
@@ -155,6 +160,7 @@ public class OmemoMessage {
 
         /**
          * Create a new incoming OMEMO message.
+         *
          * @param element original OmemoElement
          * @param key message key (or transported key)
          * @param iv respective initialization vector
@@ -173,6 +179,7 @@ public class OmemoMessage {
 
         /**
          * Return the decrypted body of the message.
+         *
          * @return decrypted body
          */
         public String getBody() {
@@ -181,6 +188,7 @@ public class OmemoMessage {
 
         /**
          * Return the fingerprint of the messages sender device.
+         *
          * @return fingerprint of sender
          */
         public OmemoFingerprint getSendersFingerprint() {
@@ -189,7 +197,8 @@ public class OmemoMessage {
 
         /**
          * Return the OmemoDevice which sent the message.
-         * @return senderDevice TODO javadoc me please
+         *
+         * @return OMEMO device that sent the message.
          */
         public OmemoDevice getSenderDevice() {
             return senderDevice;
@@ -197,6 +206,7 @@ public class OmemoMessage {
 
         /**
          * Return true, if this message was sent as a preKeyMessage.
+         *
          * @return preKeyMessage or not
          */
         boolean isPreKeyMessage() {
@@ -206,6 +216,7 @@ public class OmemoMessage {
         /**
          * Return true, if the message was a KeyTransportMessage.
          * A KeyTransportMessage is a OmemoMessage without a payload.
+         *
          * @return keyTransportMessage?
          */
         public boolean isKeyTransportMessage() {
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoRatchet.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoRatchet.java
index e00815283..838784806 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoRatchet.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoRatchet.java
@@ -86,6 +86,7 @@ public abstract class OmemoRatchet<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      *
      * @param element omemoElement
      * @return tuple of cipher generated from the unpacked message key and the auth-tag
+     *
      * @throws CryptoFailedException if decryption using the double ratchet fails
      * @throws NoRawSessionException if we have no session, but the element was NOT a PreKeyMessage
      * @throws IOException if an I/O error occurred.
@@ -154,6 +155,7 @@ public abstract class OmemoRatchet<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * @param element omemoElement containing a payload.
      * @param cipherAndAuthTag cipher and authentication tag.
      * @return decrypted plain text.
+     *
      * @throws CryptoFailedException if decryption using AES key fails.
      */
     static String decryptMessageElement(OmemoElement element, CipherAndAuthTag cipherAndAuthTag)
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoService.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoService.java
index e3a502251..82266bf2a 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoService.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoService.java
@@ -98,6 +98,7 @@ import org.jxmpp.jid.Jid;
  * @param <T_ECPub>     Elliptic Curve PublicKey class
  * @param <T_Bundle>    Bundle class
  * @param <T_Ciph>      Cipher class
+ *
  * @author Paul Schaub
  */
 public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_Sess, T_Addr, T_ECPub, T_Bundle, T_Ciph>
@@ -107,22 +108,18 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
 
     private static final long MILLIS_PER_HOUR = 1000L * 60 * 60;
 
-    /**
-     * This is a singleton.
-     */
     private static OmemoService<?, ?, ?, ?, ?, ?, ?, ?, ?> INSTANCE;
 
     private OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_Sess, T_Addr, T_ECPub, T_Bundle, T_Ciph> omemoStore;
     private final HashMap<OmemoManager, OmemoRatchet<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_Sess, T_Addr, T_ECPub, T_Bundle, T_Ciph>> omemoRatchets = new HashMap<>();
 
-    /**
-     * Create a new OmemoService object. This should only happen once.
-     */
     protected OmemoService() {
+
     }
 
     /**
      * Return the singleton instance of this class. When no instance is set, throw an IllegalStateException instead.
+     *
      * @return instance.
      */
     public static OmemoService<?, ?, ?, ?, ?, ?, ?, ?, ?> getInstance() {
@@ -229,9 +226,10 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
     }
 
     /**
-     * Initialize OMEMO functionality for OmemoManager omemoManager.
+     * Initialize OMEMO functionality for the given {@link OmemoManager}.
      *
      * @param managerGuard OmemoManager we'd like to initialize.
+     *
      * @throws InterruptedException if the calling thread was interrupted.
      * @throws CorruptedOmemoKeyException if the OMEMO key is corrupted.
      * @throws XMPPException.XMPPErrorException if there was an XMPP error returned.
@@ -272,6 +270,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * @param managerGuard Logged in OmemoManager
      * @param contactsDevice OmemoDevice of the contact
      * @return ratchet update message
+     *
      * @throws NoSuchAlgorithmException if AES algorithms are not supported on this system.
      * @throws InterruptedException if the calling thread was interrupted.
      * @throws SmackException.NoResponseException if there was no response from the remote entity.
@@ -434,6 +433,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
 
     /**
      * Decrypt an OMEMO message.
+     *
      * @param managerGuard authenticated OmemoManager.
      * @param senderJid BareJid of the sender.
      * @param omemoElement omemoElement.
@@ -456,7 +456,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
         CipherAndAuthTag cipherAndAuthTag = getOmemoRatchet(manager)
                 .retrieveMessageKeyAndAuthTag(senderDevice, omemoElement);
 
-        // Retrieve senders fingerprint. TODO: Find a way to do this without the store.
+        // Retrieve senders fingerprint.
         OmemoFingerprint senderFingerprint;
         try {
             senderFingerprint = getOmemoStoreBackend().getFingerprint(manager.getOwnDevice(), senderDevice);
@@ -483,13 +483,15 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
 
     /**
      * Create an OMEMO KeyTransportElement.
+     *
      * @see <a href="https://xmpp.org/extensions/xep-0384.html#usecases-keysend">XEP-0384: Sending a key</a>.
      *
      * @param managerGuard Initialized OmemoManager.
      * @param contactsDevices set of recipient devices.
      * @param key AES-Key to be transported.
      * @param iv initialization vector to be used with the key.
-     * @return KeyTransportElement TODO javadoc me please
+     *
+     * @return a new key transport element
      *
      * @throws InterruptedException if the calling thread was interrupted.
      * @throws UndecidedOmemoIdentityException if the list of recipients contains an undecided device
@@ -577,9 +579,11 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
 
     /**
      * Publish the given OMEMO bundle to the server using PubSub.
+     *
      * @param connection our connection.
      * @param userDevice our device
      * @param bundle the bundle we want to publish
+     *
      * @throws XMPPException.XMPPErrorException if there was an XMPP error returned.
      * @throws SmackException.NotConnectedException if the XMPP connection is not connected.
      * @throws InterruptedException if the calling thread was interrupted.
@@ -598,7 +602,8 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      *
      * @param connection authenticated XMPP connection.
      * @param contact BareJid of the contact of which we want to retrieve the device list from.
-     * @return
+     * @return device list
+     *
      * @throws InterruptedException if the calling thread was interrupted.
      * @throws PubSubException.NotALeafNodeException if a PubSub leaf node operation was attempted on a non-leaf node.
      * @throws SmackException.NoResponseException if there was no response from the remote entity.
@@ -629,8 +634,10 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
 
     /**
      * Publish the given device list to the server.
+     *
      * @param connection authenticated XMPP connection.
      * @param deviceList users deviceList.
+     *
      * @throws InterruptedException if the calling thread was interrupted.
      * @throws XMPPException.XMPPErrorException if there was an XMPP error returned.
      * @throws SmackException.NotConnectedException if the XMPP connection is not connected.
@@ -645,9 +652,11 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
     }
 
     /**
+     * Refresh our own device list and publish it to the server.
+     *
+     * @param connection XMPPConnection
+     * @param userDevice our OMEMO device
      *
-     * @param connection TODO javadoc me please
-     * @param userDevice TODO javadoc me please
      * @throws InterruptedException if the calling thread was interrupted.
      * @throws PubSubException.NotALeafNodeException if a PubSub leaf node operation was attempted on a non-leaf node.
      * @throws XMPPException.XMPPErrorException if there was an XMPP error returned.
@@ -694,8 +703,9 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * Add our load the deviceList of the user from cache, delete stale devices if needed, add the users device
      * back if necessary, store the refurbished list in cache and return it.
      *
-     * @param userDevice TODO javadoc me please
-     * @return
+     * @param userDevice our own OMEMO device
+     * @return cleaned device list
+     *
      * @throws IOException if an I/O error occurred.
      */
     OmemoCachedDeviceList cleanUpDeviceList(OmemoDevice userDevice) throws IOException {
@@ -759,6 +769,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * @param connection authenticated XMPP connection
      * @param userDevice our OmemoDevice
      * @param contactsDevice OmemoDevice of a contact.
+     *
      * @throws CannotEstablishOmemoSessionException if we cannot establish a session (because of missing bundle etc.)
      * @throws SmackException.NotConnectedException if the XMPP connection is not connected.
      * @throws InterruptedException if the calling thread was interrupted.
@@ -795,6 +806,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
     /**
      * Build sessions with all devices from the set, we don't have a session with yet.
      * Return the set of all devices we have a session with afterwards.
+     *
      * @param connection authenticated XMPP connection
      * @param userDevice our OmemoDevice
      * @param devices set of devices we may want to build a session with if necessary
@@ -842,6 +854,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * @param callback OmemoTrustCallback to query the trust decisions from
      * @param devices set of OmemoDevices
      * @return set of OmemoDevices which contains all devices from the set devices, which are undecided
+     *
      * @throws IOException if an I/O error occurred.
      */
     private Set<OmemoDevice> getUndecidedDevices(OmemoDevice userDevice, OmemoTrustCallback callback, Set<OmemoDevice> devices) throws IOException {
@@ -853,7 +866,6 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
             try {
                 fingerprint = getOmemoStoreBackend().getFingerprint(userDevice, device);
             } catch (CorruptedOmemoKeyException | NoIdentityKeyException e) {
-                // TODO: Best solution?
                 LOGGER.log(Level.WARNING, "Could not load fingerprint of " + device, e);
                 undecidedDevices.add(device);
                 continue;
@@ -873,6 +885,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * @param userDevice our OmemoDevice.
      * @param contactsDevice OmemoDevice of the contact.
      * @return true if userDevice has session with contactsDevice.
+     *
      * @throws IOException if an I/O error occurred.
      */
     private boolean hasSession(OmemoDevice userDevice, OmemoDevice contactsDevice) throws IOException {
@@ -885,6 +898,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * @param omemoManager our OmemoManager
      * @param contactsBundle bundle of the contact
      * @param contactsDevice OmemoDevice of the contact
+     *
      * @throws CorruptedOmemoKeyException if the OMEMO key is corrupted.
      */
     protected abstract void processBundle(OmemoManager omemoManager,
@@ -897,6 +911,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      *
      * @param userDevice our OmemoDevice
      * @return true if rotation is necessary
+     *
      * @throws IOException if an I/O error occurred.
      */
     private boolean shouldRotateSignedPreKey(OmemoDevice userDevice) throws IOException {
@@ -922,10 +937,11 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * This method ignores {@link OmemoConfiguration#getDeleteStaleDevices()}!
      *
      * In this case, a stale device is one of our devices, from which we haven't received an OMEMO message from
-     * for more than {@link OmemoConfiguration#DELETE_STALE_DEVICE_AFTER_HOURS} hours.
+     * for more than {@link OmemoConfiguration#getDeleteStaleDevicesAfterHours()} hours.
      *
      * @param userDevice our OmemoDevice
      * @return our altered deviceList with stale devices marked as inactive.
+     *
      * @throws IOException if an I/O error occurred.
      */
     private OmemoCachedDeviceList deleteStaleDevices(OmemoDevice userDevice) throws IOException {
@@ -946,6 +962,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * @param contact subjects BareJid.
      * @param contactsDeviceList subjects deviceList.
      * @return copy of subjects deviceList with stale devices marked as inactive.
+     *
      * @throws IOException if an I/O error occurred.
      */
     private OmemoCachedDeviceList removeStaleDevicesFromDeviceList(OmemoDevice userDevice,
@@ -1001,7 +1018,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * @param lastReceipt date of last received message from that device
      * @param maxAgeHours threshold
      *
-     * @return staleness TODO javadoc me please
+     * @return true if the subject device is considered stale
      */
     static boolean isStale(OmemoDevice userDevice, OmemoDevice subject, Date lastReceipt, int maxAgeHours) {
         if (userDevice.equals(subject)) {
@@ -1042,7 +1059,8 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      *
      * @param managerGuard authenticated OmemoManager.
      * @param mamQuery Mam archive query
-     * @return list of {@link MessageOrOmemoMessage}s.
+     * @return list of {@link MessageOrOmemoMessage MessageOrOmemoMessages}.
+     *
      * @throws IOException if an I/O error occurred.
      */
     List<MessageOrOmemoMessage> decryptMamQueryResult(OmemoManager.LoggedInOmemoManager managerGuard,
@@ -1123,8 +1141,8 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
                     OmemoBundleElement bundleElement = getOmemoStoreBackend().packOmemoBundle(userDevice);
                     publishBundle(manager.getConnection(), userDevice, bundleElement);
                 } catch (CorruptedOmemoKeyException | InterruptedException | SmackException.NoResponseException
-                                | SmackException.NotConnectedException | XMPPException.XMPPErrorException
-                                | NotALeafNodeException e) {
+                        | SmackException.NotConnectedException | XMPPException.XMPPErrorException
+                        | NotALeafNodeException e) {
                     LOGGER.log(Level.WARNING, "Could not republish replenished bundle.", e);
                 }
             }
@@ -1206,8 +1224,8 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
                     OmemoBundleElement bundleElement = getOmemoStoreBackend().packOmemoBundle(userDevice);
                     publishBundle(manager.getConnection(), userDevice, bundleElement);
                 } catch (CorruptedOmemoKeyException | InterruptedException | SmackException.NoResponseException
-                                | SmackException.NotConnectedException | XMPPException.XMPPErrorException
-                                | NotALeafNodeException e) {
+                        | SmackException.NotConnectedException | XMPPException.XMPPErrorException
+                        | NotALeafNodeException e) {
                     LOGGER.log(Level.WARNING, "Could not republish replenished bundle.", e);
                 }
             }
@@ -1221,6 +1239,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * @param stanza stanza
      * @param managerGuard authenticated OmemoManager
      * @return decrypted OmemoMessage or null
+     *
      * @throws IOException if an I/O error occurred.
      */
     OmemoMessage.Received decryptStanza(Stanza stanza, OmemoManager.LoggedInOmemoManager managerGuard) throws IOException {
@@ -1288,8 +1307,8 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
                     OmemoBundleElement bundleElement = getOmemoStoreBackend().packOmemoBundle(userDevice);
                     publishBundle(manager.getConnection(), userDevice, bundleElement);
                 } catch (CorruptedOmemoKeyException | InterruptedException | SmackException.NoResponseException
-                                | SmackException.NotConnectedException | XMPPException.XMPPErrorException
-                                | NotALeafNodeException e) {
+                        | SmackException.NotConnectedException | XMPPException.XMPPErrorException
+                        | NotALeafNodeException e) {
                     LOGGER.log(Level.WARNING, "Could not republish replenished bundle.", e);
                 }
             }
@@ -1302,6 +1321,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      *
      * @param managerGuard authenticated OmemoManager.
      * @param brokenDevice device which session broke.
+     *
      * @throws IOException if an I/O error occurred.
      */
     private void repairBrokenSessionWithPreKeyMessage(OmemoManager.LoggedInOmemoManager managerGuard,
@@ -1326,8 +1346,10 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
 
     /**
      * Send an empty OMEMO message to contactsDevice in order to forward the ratchet.
-     * @param managerGuard TODO javadoc me please
-     * @param contactsDevice TODO javadoc me please
+     *
+     * @param managerGuard OMEMO manager
+     * @param contactsDevice contacts OMEMO device
+     *
      * @throws CorruptedOmemoKeyException if our or their OMEMO key is corrupted.
      * @throws InterruptedException if the calling thread was interrupted.
      * @throws SmackException.NoResponseException if there was no response from the remote entity.
@@ -1355,6 +1377,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
 
     /**
      * Return the joined MUC with EntityBareJid jid, or null if its not a room and/or not joined.
+     *
      * @param connection xmpp connection
      * @param jid jid (presumably) of the MUC
      * @return MultiUserChat or null if not a MUC.
@@ -1378,6 +1401,7 @@ public abstract class OmemoService<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * Publish a new DeviceList with just our device in it.
      *
      * @param managerGuard authenticated OmemoManager.
+     *
      * @throws InterruptedException if the calling thread was interrupted.
      * @throws XMPPException.XMPPErrorException if there was an XMPP error returned.
      * @throws SmackException.NotConnectedException if the XMPP connection is not connected.
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoStore.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoStore.java
index a4d02b89b..395a1745f 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoStore.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/OmemoStore.java
@@ -53,6 +53,7 @@ import org.jxmpp.jid.BareJid;
  * @param <T_ECPub>     Elliptic Curve PublicKey class
  * @param <T_Bundle>    Bundle class
  * @param <T_Ciph>      Cipher class
+ *
  * @author Paul Schaub
  */
 public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_Sess, T_Addr, T_ECPub, T_Bundle, T_Ciph> {
@@ -68,6 +69,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
     /**
      * Returns a sorted set of all the deviceIds, the localUser has had data stored under in the store.
      * Basically this returns the deviceIds of all "accounts" of localUser, which are known to the store.
+     *
      * @param localUser BareJid of the user.
      * @return set of deviceIds with available data.
      */
@@ -79,6 +81,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice    our current device.
      * @param id            deviceId to check for.
      * @return true if list did not contain our id, else false
+     *
      * @throws IOException if an I/O error occurred.
      */
     boolean isAvailableDeviceId(OmemoDevice userDevice, int id) throws IOException {
@@ -103,6 +106,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice.
      * @param contact Contact we received the list from.
      * @param list    List we received.
+     *
      * @throws IOException if an I/O error occurred.
      */
     OmemoCachedDeviceList mergeCachedDeviceList(OmemoDevice userDevice, BareJid contact, OmemoDeviceListElement list) throws IOException {
@@ -133,6 +137,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * The old signed PreKey should be kept for around a month or so (look it up in the XEP).
      *
      * @param userDevice our OmemoDevice.
+     *
      * @throws CorruptedOmemoKeyException when our identityKey is invalid.
      * @throws IOException if an I/O error occurred.
      * @throws IllegalStateException when our IdentityKeyPair is null.
@@ -163,6 +168,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * Remove the oldest signedPreKey until there are only MAX_NUMBER_OF_STORED_SIGNED_PREKEYS left.
      *
      * @param userDevice our OmemoDevice.
+     *
      * @throws IOException if an I/O error occurred.
      */
     private void removeOldSignedPreKeys(OmemoDevice userDevice) throws IOException {
@@ -184,7 +190,8 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * Pack a OmemoBundleElement containing our key material.
      *
      * @param userDevice our OmemoDevice.
-     * @return OmemoBundleElement TODO javadoc me please
+     * @return OMEMO bundle element
+     *
      * @throws CorruptedOmemoKeyException when a key could not be loaded
      * @throws IOException if an I/O error occurred.
      */
@@ -205,7 +212,9 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
 
     /**
      * Replenish our supply of keys. If we are missing any type of keys, generate them fresh.
-     * @param userDevice TODO javadoc me please
+     *
+     * @param userDevice our own OMEMO device
+     *
      * @throws CorruptedOmemoKeyException if the OMEMO key is corrupted.
      * @throws IOException if an I/O error occurred.
      */
@@ -238,7 +247,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
     /**
      * Generate a new IdentityKeyPair. We should always have only one pair and usually keep this for a long time.
      *
-     * @return identityKeyPair TODO javadoc me please
+     * @return a fresh identityKeyPair
      */
     public T_IdKeyPair generateOmemoIdentityKeyPair() {
         return keyUtil().generateOmemoIdentityKeyPair();
@@ -249,7 +258,8 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * Return null, if we have no identityKeyPair.
      *
      * @param userDevice our OmemoDevice.
-     * @return identityKeyPair TODO javadoc me please
+     * @return loaded identityKeyPair
+     *
      * @throws CorruptedOmemoKeyException Thrown, if the stored key is damaged (*hands up* not my fault!)
      * @throws IOException if an I/O error occurred.
      */
@@ -262,12 +272,14 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      *
      * @param userDevice our OmemoDevice.
      * @param identityKeyPair identityKeyPair
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract void storeOmemoIdentityKeyPair(OmemoDevice userDevice, T_IdKeyPair identityKeyPair) throws IOException;
 
     /**
      * Remove the identityKeyPair of a user.
+     *
      * @param userDevice our device.
      */
     public abstract void removeOmemoIdentityKeyPair(OmemoDevice userDevice);
@@ -277,7 +289,8 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      *
      * @param userDevice our OmemoDevice.
      * @param contactsDevice the device of which we want to load the identityKey.
-     * @return identityKey TODO javadoc me please
+     * @return loaded identityKey
+     *
      * @throws CorruptedOmemoKeyException when the key in question is corrupted and cant be deserialized.
      * @throws IOException if an I/O error occurred.
      */
@@ -290,6 +303,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice.
      * @param contactsDevice device.
      * @param contactsKey    identityKey belonging to the contactsDevice.
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract void storeOmemoIdentityKey(OmemoDevice userDevice, OmemoDevice contactsDevice, T_IdKey contactsKey) throws IOException;
@@ -309,6 +323,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our omemoDevice.
      * @param contactsDevice device of which we want to set the message counter.
      * @param counter counter value.
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract void storeOmemoMessageCounter(OmemoDevice userDevice, OmemoDevice contactsDevice, int counter) throws IOException;
@@ -321,6 +336,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our omemoDevice
      * @param contactsDevice device of which we want to get the message counter.
      * @return counter value.
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract int loadOmemoMessageCounter(OmemoDevice userDevice, OmemoDevice contactsDevice) throws IOException;
@@ -331,6 +347,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice omemoManager of our device.
      * @param contactsDevice device in question
      * @param date date of the last received message
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract void setDateOfLastReceivedMessage(OmemoDevice userDevice, OmemoDevice contactsDevice, Date date) throws IOException;
@@ -341,6 +358,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice.
      * @param contactsDevice device in question
      * @return date if existent, null
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract Date getDateOfLastReceivedMessage(OmemoDevice userDevice, OmemoDevice contactsDevice) throws IOException;
@@ -352,6 +370,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice
      * @param contactsDevice OmemoDevice in question
      * @param date date of the last publication after not being published
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract void setDateOfLastDeviceIdPublication(OmemoDevice userDevice, OmemoDevice contactsDevice, Date date) throws IOException;
@@ -363,6 +382,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice
      * @param contactsDevice OmemoDevice in question
      * @return date of the last publication after not being published
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract Date getDateOfLastDeviceIdPublication(OmemoDevice userDevice, OmemoDevice contactsDevice) throws IOException;
@@ -372,6 +392,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      *
      * @param userDevice our OmemoDevice.
      * @param date date
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract void setDateOfLastSignedPreKeyRenewal(OmemoDevice userDevice, Date date) throws IOException;
@@ -381,6 +402,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      *
      * @param userDevice our OmemoDevice.
      * @return date if existent, otherwise null
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract Date getDateOfLastSignedPreKeyRenewal(OmemoDevice userDevice) throws IOException;
@@ -403,6 +425,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice.
      * @param preKeyId id of the key to be loaded
      * @return loaded preKey
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract T_PreKey loadOmemoPreKey(OmemoDevice userDevice, int preKeyId) throws IOException;
@@ -413,6 +436,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice.
      * @param preKeyId id of the key
      * @param preKey   key
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract void storeOmemoPreKey(OmemoDevice userDevice, int preKeyId, T_PreKey preKey) throws IOException;
@@ -422,6 +446,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      *
      * @param userDevice our OmemoDevice.
      * @param preKeyHashMap HashMap of preKeys
+     *
      * @throws IOException if an I/O error occurred.
      */
     public void storeOmemoPreKeys(OmemoDevice userDevice, TreeMap<Integer, T_PreKey> preKeyHashMap) throws IOException {
@@ -444,6 +469,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      *
      * @param userDevice our OmemoDevice.
      * @return Map containing our preKeys
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract TreeMap<Integer, T_PreKey> loadOmemoPreKeys(OmemoDevice userDevice) throws IOException;
@@ -453,7 +479,8 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      *
      * @param userDevice our OmemoDevice.
      * @param signedPreKeyId id of the key
-     * @return key TODO javadoc me please
+     * @return loaded signed preKey
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract T_SigPreKey loadOmemoSignedPreKey(OmemoDevice userDevice, int signedPreKeyId) throws IOException;
@@ -467,6 +494,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      *
      * @param userDevice our OmemoDevice.
      * @return HashMap of our singedPreKeys
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract TreeMap<Integer, T_SigPreKey> loadOmemoSignedPreKeys(OmemoDevice userDevice) throws IOException;
@@ -476,7 +504,8 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      *
      * @param identityKeyPair identityKeyPair used to sign the preKey
      * @param signedPreKeyId  id that the preKey will have
-     * @return signedPreKey TODO javadoc me please
+     * @return a fresh signedPreKey
+     *
      * @throws CorruptedOmemoKeyException when something goes wrong
      */
     public T_SigPreKey generateOmemoSignedPreKey(T_IdKeyPair identityKeyPair, int signedPreKeyId)
@@ -490,6 +519,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice.
      * @param signedPreKeyId id of the signedPreKey
      * @param signedPreKey   the key itself
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract void storeOmemoSignedPreKey(OmemoDevice userDevice, int signedPreKeyId, T_SigPreKey signedPreKey) throws IOException;
@@ -508,6 +538,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice.
      * @param contactsDevice device whose session we want to load
      * @return crypto related session
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract T_Sess loadRawSession(OmemoDevice userDevice, OmemoDevice contactsDevice) throws IOException;
@@ -518,6 +549,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice.
      * @param contact BareJid of the contact we want to get all sessions from
      * @return TreeMap of deviceId and sessions of the contact
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract HashMap<Integer, T_Sess> loadAllRawSessionsOf(OmemoDevice userDevice, BareJid contact) throws IOException;
@@ -528,6 +560,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice.
      * @param contactsDevice  OmemoDevice whose session we want to store
      * @param session session
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract void storeRawSession(OmemoDevice userDevice, OmemoDevice contactsDevice, T_Sess session) throws IOException;
@@ -564,6 +597,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice.
      * @param contact contact we want to get the deviceList of
      * @return CachedDeviceList of the contact
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract OmemoCachedDeviceList loadCachedDeviceList(OmemoDevice userDevice, BareJid contact) throws IOException;
@@ -571,8 +605,9 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
     /**
      * Load a list of deviceIds from our own devices.
      *
-     * @param userDevice TODO javadoc me please
+     * @param userDevice our own OMEMO device
      * @return the cached OMEMO device list.
+     *
      * @throws IOException if an I/O error occurred.
      */
     public OmemoCachedDeviceList loadCachedDeviceList(OmemoDevice userDevice) throws IOException {
@@ -586,6 +621,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice.
      * @param contact    Contact
      * @param contactsDeviceList list of the contacts devices' ids.
+     *
      * @throws IOException if an I/O error occurred.
      */
     public abstract void storeCachedDeviceList(OmemoDevice userDevice,
@@ -632,6 +668,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param userDevice our OmemoDevice.
      * @param contactsDevice OmemoDevice we want to have the fingerprint for.
      * @return fingerprint of the userDevices IdentityKey.
+     *
      * @throws CorruptedOmemoKeyException if the IdentityKey is corrupted.
      * @throws NoIdentityKeyException if no IdentityKey for contactsDevice has been found locally.
      * @throws IOException if an I/O error occurred.
@@ -652,7 +689,7 @@ public abstract class OmemoStore<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      *
      * @param managerGuard authenticated OmemoManager
      * @param contactsDevice OmemoDevice we want to get the fingerprint from
-     * @return fingerprint TODO javadoc me please
+     * @return fingerprint of the contacts OMEMO device
      *
      * @throws CannotEstablishOmemoSessionException If we have no local copy of the identityKey of the contact
      *                                              and are unable to build a fresh session
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoBundleElement.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoBundleElement.java
index 777dd0b22..217c27f6d 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoBundleElement.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoBundleElement.java
@@ -158,7 +158,7 @@ public abstract class OmemoBundleElement implements ExtensionElement {
      * Return the HashMap of preKeys in the bundle.
      * The map uses the preKeys ids as key and the preKeys as value.
      *
-     * @return preKeys TODO javadoc me please
+     * @return preKeys Pre-Keys contained in the bundle
      */
     public HashMap<Integer, byte[]> getPreKeys() {
         if (preKeys == null) {
@@ -209,15 +209,17 @@ public abstract class OmemoBundleElement implements ExtensionElement {
 
     @Override
     public String toString() {
-        String out = "OmemoBundleElement[\n";
-        out += SIGNED_PRE_KEY_PUB + " " + SIGNED_PRE_KEY_ID + "=" + signedPreKeyId + ": " + signedPreKeyB64 + "\n";
-        out += SIGNED_PRE_KEY_SIG + ": " + signedPreKeySignatureB64 + "\n";
-        out += IDENTITY_KEY + ": " + identityKeyB64 + "\n";
-        out += PRE_KEYS + " (" + preKeysB64.size() + ")\n";
+        StringBuilder sb = new StringBuilder("OmemoBundleElement[\n");
+        sb.append(SIGNED_PRE_KEY_PUB).append(' ').append(SIGNED_PRE_KEY_ID).append('=').append(signedPreKeyId)
+                .append(':').append(signedPreKeyB64).append('\n')
+                .append(SIGNED_PRE_KEY_SIG).append(": ").append(signedPreKeySignatureB64).append('\n')
+                .append(IDENTITY_KEY).append(": ").append(identityKeyB64).append('\n')
+                .append(PRE_KEYS).append(" (").append(preKeysB64.size()).append(")\n");
         for (Map.Entry<Integer, String> e : preKeysB64.entrySet()) {
-            out += PRE_KEY_PUB + " " + PRE_KEY_ID + "=" + e.getKey() + ": " + e.getValue() + "\n";
+            sb.append(PRE_KEY_PUB).append(' ').append(PRE_KEY_ID).append('=').append(e.getKey()).append(": ").append(e.getValue()).append('\n');
         }
-        return out;
+        sb.append(']');
+        return sb.toString();
     }
 
     @Override
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoBundleElement_VAxolotl.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoBundleElement_VAxolotl.java
index 945a6611f..736afa37d 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoBundleElement_VAxolotl.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoBundleElement_VAxolotl.java
@@ -21,8 +21,9 @@ import static org.jivesoftware.smackx.omemo.util.OmemoConstants.OMEMO_NAMESPACE_
 import java.util.HashMap;
 
 /**
- * OMEMO device bundle as described here:
- * https://xmpp.org/extensions/xep-0384.html#usecases-announcing (Example 3).
+ * OMEMO device bundle as described by the protocol.
+ *
+ * @see <a href="https://xmpp.org/extensions/xep-0384.html#usecases-announcing">XEP-0384: OMEMO Encryption (Example 3)</a>.
  *
  * @author Paul Schaub
  */
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoDeviceListElement.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoDeviceListElement.java
index 2b2515cb4..8644586d0 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoDeviceListElement.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoDeviceListElement.java
@@ -18,6 +18,7 @@ package org.jivesoftware.smackx.omemo.element;
 
 import java.util.Collections;
 import java.util.HashSet;
+import java.util.Iterator;
 import java.util.Set;
 
 import org.jivesoftware.smack.packet.ExtensionElement;
@@ -78,10 +79,14 @@ public abstract class OmemoDeviceListElement implements ExtensionElement {
 
     @Override
     public final String toString() {
-        String out = "OmemoDeviceListElement[";
+        StringBuilder sb = new StringBuilder("OmemoDeviceListElement[");
+        Iterator<Integer> iterator = deviceIds.iterator();
         for (int i : deviceIds) {
-            out += i + ",";
+            sb.append(i);
+            if (iterator.hasNext()) {
+                sb.append(',');
+            }
         }
-        return out.substring(0, out.length() - 1) + "]";
+        return sb.append(']').toString();
     }
 }
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoElement.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoElement.java
index 6d28da919..fea020003 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoElement.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/element/OmemoElement.java
@@ -55,7 +55,7 @@ public abstract class OmemoElement implements ExtensionElement {
     /**
      * Return the payload of the message.
      *
-     * @return payload TODO javadoc me please
+     * @return encrypted payload of the message.
      */
     public byte[] getPayload() {
         if (payload == null) {
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/CannotEstablishOmemoSessionException.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/CannotEstablishOmemoSessionException.java
index e20782632..2d4e65513 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/CannotEstablishOmemoSessionException.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/CannotEstablishOmemoSessionException.java
@@ -79,7 +79,8 @@ public class CannotEstablishOmemoSessionException extends Exception {
     /**
      * Return true, if there is at least one recipient, which would not be able to decipher the message on any of
      * their devices.
-     * @return boolean TODO javadoc me please
+     *
+     * @return true if the exception requires to be thrown
      */
     public boolean requiresThrowing() {
         for (Map.Entry<BareJid, HashMap<OmemoDevice, Throwable>> entry : failures.entrySet()) {
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/MultipleCryptoFailedException.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/MultipleCryptoFailedException.java
index 8627823f9..8a890cca0 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/MultipleCryptoFailedException.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/MultipleCryptoFailedException.java
@@ -22,9 +22,6 @@ import java.util.List;
 
 public final class MultipleCryptoFailedException extends CryptoFailedException {
 
-    /**
-     *
-     */
     private static final long serialVersionUID = 1L;
 
     private final List<CryptoFailedException> cryptoFailedExceptions;
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/ReadOnlyDeviceException.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/ReadOnlyDeviceException.java
index ce69d1a30..cc82bc365 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/ReadOnlyDeviceException.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/ReadOnlyDeviceException.java
@@ -44,7 +44,8 @@ public class ReadOnlyDeviceException extends Exception {
 
     /**
      * Return the device in question.
-     * @return device TODO javadoc me please
+     *
+     * @return device that is read-only.
      */
     public OmemoDevice getDevice() {
         return device;
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/StaleDeviceException.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/StaleDeviceException.java
index c3453b99e..948eac040 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/StaleDeviceException.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/StaleDeviceException.java
@@ -31,8 +31,8 @@ public class StaleDeviceException extends Exception {
      * This exception gets thrown if a message cannot be encrypted for a device due to the device being inactive for too long (stale).
      *
      * @param device OmemoDevice.
-     * @param lastMessageDate TODO javadoc me please
-     * @param lastDeviceIdPublicationDate TODO javadoc me please
+     * @param lastMessageDate date of the last received message from the device.
+     * @param lastDeviceIdPublicationDate date on which the device ID was last published via pubsub.
      */
     public StaleDeviceException(OmemoDevice device, Date lastMessageDate, Date lastDeviceIdPublicationDate) {
         this.device = device;
@@ -42,6 +42,7 @@ public class StaleDeviceException extends Exception {
 
     /**
      * Return the date on which the last OMEMO message sent from the device was received.
+     *
      * @return last messages date
      */
     public Date getLastMessageDate() {
@@ -50,6 +51,7 @@ public class StaleDeviceException extends Exception {
 
     /**
      * Return the date of the last time the deviceId was republished after being inactive/non-existent before.
+     *
      * @return date of last deviceId (re)publication.
      */
     public Date getLastDeviceIdPublicationDate() {
@@ -58,6 +60,7 @@ public class StaleDeviceException extends Exception {
 
     /**
      * Return the stale OMEMO device.
+     *
      * @return stale device
      */
     public OmemoDevice getDevice() {
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/UntrustedOmemoIdentityException.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/UntrustedOmemoIdentityException.java
index 3e8b0b458..ab5eac9ce 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/UntrustedOmemoIdentityException.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/exceptions/UntrustedOmemoIdentityException.java
@@ -56,6 +56,7 @@ public class UntrustedOmemoIdentityException extends Exception {
 
     /**
      * Return the device which sent the message.
+     *
      * @return omemoDevice.
      */
     public OmemoDevice getDevice() {
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/internal/CiphertextTuple.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/internal/CiphertextTuple.java
index 60fac8469..32483d17c 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/internal/CiphertextTuple.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/internal/CiphertextTuple.java
@@ -41,7 +41,7 @@ public class CiphertextTuple {
     /**
      * Return the ciphertext.
      *
-     * @return ciphertext TODO javadoc me please
+     * @return ciphertext part of the tuple
      */
     public byte[] getCiphertext() {
         return ciphertext;
@@ -50,7 +50,7 @@ public class CiphertextTuple {
     /**
      * Return the messageType.
      *
-     * @return messageType TODO javadoc me please
+     * @return type of the message
      */
     public int getMessageType() {
         return this.messageType;
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/internal/OmemoDevice.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/internal/OmemoDevice.java
index 762494281..11041f0c2 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/internal/OmemoDevice.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/internal/OmemoDevice.java
@@ -43,7 +43,7 @@ public class OmemoDevice {
     /**
      * Return the BareJid of the device owner.
      *
-     * @return bareJid TODO javadoc me please
+     * @return bare JID of the device owner.
      */
     public BareJid getJid() {
         return this.jid;
@@ -52,7 +52,7 @@ public class OmemoDevice {
     /**
      * Return the OMEMO device Id of the device.
      *
-     * @return deviceId TODO javadoc me please
+     * @return OMEMO device ID.
      */
     public int getDeviceId() {
         return this.deviceId;
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/listener/OmemoMucMessageListener.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/listener/OmemoMucMessageListener.java
index 90683e5ee..3bccac5cf 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/listener/OmemoMucMessageListener.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/listener/OmemoMucMessageListener.java
@@ -23,12 +23,14 @@ import org.jivesoftware.smackx.omemo.OmemoMessage;
 
 /**
  * Listener interface that allows implementations to receive decrypted OMEMO MUC messages.
+ *
  * @author Paul Schaub
  */
 public interface OmemoMucMessageListener {
 
     /**
      * Gets called whenever an OMEMO message has been received in a MultiUserChat and successfully decrypted.
+     *
      * @param muc MultiUserChat the message was sent in
      * @param stanza Original Stanza
      * @param decryptedOmemoMessage decrypted Omemo message
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/trust/TrustState.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/trust/TrustState.java
index 605298c26..8ad2d2ae0 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/trust/TrustState.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/trust/TrustState.java
@@ -17,7 +17,16 @@
 package org.jivesoftware.smackx.omemo.trust;
 
 public enum TrustState {
-    undecided, // User has yet to decide, whether the identity is trusted or not.
-    untrusted, // User decided NOT to trust this device.
-    trusted    // User decided to trust this device.
+    /**
+     * User has yet to decide, whether the identity is trusted or not.
+     */
+    undecided,
+    /**
+     * User decided NOT to trust this device.
+     */
+    untrusted,
+    /**
+     * User decided to trust this device.
+     */
+    trusted
 }
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/util/OmemoConstants.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/util/OmemoConstants.java
index 885260568..f91dc199f 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/util/OmemoConstants.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/util/OmemoConstants.java
@@ -18,11 +18,11 @@ package org.jivesoftware.smackx.omemo.util;
 
 /**
  * Some constants related to OMEMO.
+ *
  * @author Paul Schaub
  */
 public final class OmemoConstants {
 
-    // Constants
     /**
      * Omemo related namespace.
      */
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/util/OmemoKeyUtil.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/util/OmemoKeyUtil.java
index 1954246f1..607181552 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/util/OmemoKeyUtil.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/util/OmemoKeyUtil.java
@@ -55,7 +55,8 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
          * Extract an IdentityKey from a OmemoBundleElement.
          *
          * @param bundle OmemoBundleElement
-         * @return identityKey TODO javadoc me please
+         * @return identityKey of the bundle
+         *
          * @throws CorruptedOmemoKeyException if the key is damaged/malformed
          */
         public T_IdKey identityKey(OmemoBundleElement bundle) throws CorruptedOmemoKeyException {
@@ -66,7 +67,8 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
          * Extract a signedPreKey from an OmemoBundleElement.
          *
          * @param bundle OmemoBundleElement
-         * @return singedPreKey TODO javadoc me please
+         * @return signed preKey
+         *
          * @throws CorruptedOmemoKeyException if the key is damaged/malformed
          */
         public T_ECPub signedPreKeyPublic(OmemoBundleElement bundle) throws CorruptedOmemoKeyException {
@@ -77,7 +79,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
          * Extract the id of the transported signedPreKey from the bundle.
          *
          * @param bundle OmemoBundleElement
-         * @return signedPreKeyId TODO javadoc me please
+         * @return id of the signed preKey
          */
         public int signedPreKeyId(OmemoBundleElement bundle) {
             return bundle.getSignedPreKeyId();
@@ -87,7 +89,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
          * Extract the signature of the signedPreKey in the bundle as a byte array.
          *
          * @param bundle OmemoBundleElement
-         * @return signature TODO javadoc me please
+         * @return signature on the signed preKey
          */
         public byte[] signedPreKeySignature(OmemoBundleElement bundle) {
             return bundle.getSignedPreKeySignature();
@@ -99,6 +101,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
          * @param bundle OmemoBundleElement
          * @param keyId  id of the preKey
          * @return the preKey
+         *
          * @throws CorruptedOmemoKeyException when the key cannot be parsed from bytes
          */
         public T_ECPub preKeyPublic(OmemoBundleElement bundle, int keyId) throws CorruptedOmemoKeyException {
@@ -113,6 +116,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
          * @param bundle  OmemoBundleElement containing multiple PreKeys
          * @param contact Contact that the bundle belongs to
          * @return a HashMap with one T_Bundle per preKey and the preKeyId as key
+         *
          * @throws CorruptedOmemoKeyException when one of the keys cannot be parsed
          */
         public HashMap<Integer, T_Bundle> bundles(OmemoBundleElement bundle, OmemoDevice contact) throws CorruptedOmemoKeyException {
@@ -136,6 +140,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      *
      * @param data byte array
      * @return IdentityKeyPair (T_IdKeyPair)
+     *
      * @throws CorruptedOmemoKeyException if the key is damaged of malformed
      */
     public abstract T_IdKeyPair identityKeyPairFromBytes(byte[] data) throws CorruptedOmemoKeyException;
@@ -145,6 +150,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      *
      * @param data byte array
      * @return identityKey (T_IdKey)
+     *
      * @throws CorruptedOmemoKeyException if the key is damaged or malformed
      */
     public abstract T_IdKey identityKeyFromBytes(byte[] data) throws CorruptedOmemoKeyException;
@@ -153,7 +159,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * Serialize an identityKey into bytes.
      *
      * @param identityKey idKey
-     * @return bytes TODO javadoc me please
+     * @return byte array representation of the identity key.
      */
     public abstract byte[] identityKeyToBytes(T_IdKey identityKey);
 
@@ -162,6 +168,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      *
      * @param data bytes
      * @return elliptic curve public key (T_ECPub)
+     *
      * @throws CorruptedOmemoKeyException if the key is damaged or malformed
      */
     public abstract T_ECPub ellipticCurvePublicKeyFromBytes(byte[] data) throws CorruptedOmemoKeyException;
@@ -170,7 +177,8 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * Deserialize a public preKey from bytes.
      *
      * @param data preKey as bytes
-     * @return preKey TODO javadoc me please
+     * @return deserialized preKey
+     *
      * @throws CorruptedOmemoKeyException if the key is damaged or malformed
      */
     public T_ECPub preKeyPublicFromBytes(byte[] data) throws CorruptedOmemoKeyException {
@@ -190,6 +198,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      *
      * @param bytes byte array
      * @return deserialized preKey
+     *
      * @throws IOException when something goes wrong
      */
     public abstract T_PreKey preKeyFromBytes(byte[] bytes) throws IOException;
@@ -209,7 +218,8 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      *
      * @param identityKeyPair identityKeyPair used to sign the preKey
      * @param signedPreKeyId  id that the preKey will have
-     * @return signedPreKey TODO javadoc me please
+     * @return deserialized signed preKey
+     *
      * @throws CorruptedOmemoKeyException when the identityKeyPair is invalid
      */
     public abstract T_SigPreKey generateOmemoSignedPreKey(T_IdKeyPair identityKeyPair, int signedPreKeyId) throws CorruptedOmemoKeyException;
@@ -219,7 +229,8 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * Deserialize a public signedPreKey from bytes.
      *
      * @param data bytes
-     * @return signedPreKey TODO javadoc me please
+     * @return deserialized signed preKey
+     *
      * @throws CorruptedOmemoKeyException if the key is damaged or malformed
      */
     public T_ECPub signedPreKeyPublicFromBytes(byte[] data) throws CorruptedOmemoKeyException {
@@ -231,6 +242,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      *
      * @param data byte array
      * @return deserialized signed preKey
+     *
      * @throws IOException when something goes wrong
      */
     public abstract T_SigPreKey signedPreKeyFromBytes(byte[] data) throws IOException;
@@ -252,6 +264,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      * @param contact Contact that the bundle belongs to
      * @param keyId   id of the preKey that will be selected from the OmemoBundleElement and that the PreKeyBundle will contain
      * @return PreKeyBundle (T_PreKey)
+     *
      * @throws CorruptedOmemoKeyException if some key is damaged or malformed
      */
     public abstract T_Bundle bundleFromOmemoBundle(OmemoBundleElement bundle, OmemoDevice contact, int keyId) throws CorruptedOmemoKeyException;
@@ -267,7 +280,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
     /**
      * Generate a new IdentityKeyPair. We should always have only one pair and usually keep this for a long time.
      *
-     * @return identityKeyPair TODO javadoc me please
+     * @return deserialized identity key pair
      */
     public abstract T_IdKeyPair generateOmemoIdentityKeyPair();
 
@@ -361,6 +374,7 @@ public abstract class OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey,
      *
      * @param data bytes
      * @return raw OMEMO Session
+     *
      * @throws IOException when something goes wrong
      */
     public abstract T_Sess rawSessionFromBytes(byte[] data) throws IOException;
diff --git a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/util/OmemoMessageBuilder.java b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/util/OmemoMessageBuilder.java
index 1f20e39cc..6e49db945 100644
--- a/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/util/OmemoMessageBuilder.java
+++ b/smack-omemo/src/main/java/org/jivesoftware/smackx/omemo/util/OmemoMessageBuilder.java
@@ -21,15 +21,12 @@ import static org.jivesoftware.smackx.omemo.util.OmemoConstants.Crypto.KEYLENGTH
 import static org.jivesoftware.smackx.omemo.util.OmemoConstants.Crypto.KEYTYPE;
 
 import java.io.IOException;
-import java.io.UnsupportedEncodingException;
 import java.nio.charset.StandardCharsets;
 import java.security.InvalidAlgorithmParameterException;
 import java.security.InvalidKeyException;
 import java.security.NoSuchAlgorithmException;
-import java.security.NoSuchProviderException;
 import java.security.SecureRandom;
 import java.util.ArrayList;
-
 import javax.crypto.BadPaddingException;
 import javax.crypto.Cipher;
 import javax.crypto.IllegalBlockSizeException;
@@ -128,7 +125,6 @@ public class OmemoMessageBuilder<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @throws InvalidKeyException if the key is invalid.
      * @throws NoSuchAlgorithmException if no such algorithm is available.
      * @throws IllegalBlockSizeException if the input data length is incorrect.
-     * @throws UnsupportedEncodingException if the encoding is not supported.
      * @throws InvalidAlgorithmParameterException if the provided arguments are invalid.
      */
     public OmemoMessageBuilder(OmemoDevice userDevice,
@@ -136,7 +132,7 @@ public class OmemoMessageBuilder<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
                                OmemoRatchet<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_Sess, T_Addr, T_ECPub, T_Bundle, T_Ciph> ratchet,
                                String message)
             throws NoSuchPaddingException, BadPaddingException, InvalidKeyException, NoSuchAlgorithmException, IllegalBlockSizeException,
-            UnsupportedEncodingException, InvalidAlgorithmParameterException {
+            InvalidAlgorithmParameterException {
         this(userDevice, callback, ratchet, generateKey(KEYTYPE, KEYLENGTH), generateIv(), message);
     }
 
@@ -144,19 +140,20 @@ public class OmemoMessageBuilder<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * Encrypt the message with the aes key.
      * Move the AuthTag from the end of the cipherText to the end of the messageKey afterwards.
      * This prevents an attacker which compromised one recipient device to switch out the cipherText for other recipients.
+     *
      * @see <a href="https://conversations.im/omemo/audit.pdf">OMEMO security audit</a>.
      *
      * @param message plaintext message
+     *
      * @throws NoSuchPaddingException if the requested padding mechanism is not availble.
-     * @throws NoSuchProviderException
      * @throws InvalidAlgorithmParameterException if the provided arguments are invalid.
      * @throws InvalidKeyException if the key is invalid.
      * @throws BadPaddingException if the input data is not padded properly.
      * @throws IllegalBlockSizeException if the input data length is incorrect.
      */
     private void setMessage(String message)
-                    throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidAlgorithmParameterException,
-                    InvalidKeyException, BadPaddingException, IllegalBlockSizeException {
+            throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidAlgorithmParameterException,
+            InvalidKeyException, BadPaddingException, IllegalBlockSizeException {
         if (message == null) {
             return;
         }
@@ -202,7 +199,7 @@ public class OmemoMessageBuilder<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
 
         if (cipherTextWithoutAuthTag.length != cipherText.length - 16) {
             throw new IllegalArgumentException("Length of cipherTextWithoutAuthTag must be length of cipherText " +
-            "- length of AuthTag (16)");
+                    "- length of AuthTag (16)");
         }
 
         // Move auth tag from cipherText to messageKey
@@ -215,6 +212,7 @@ public class OmemoMessageBuilder<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * Add a new recipient device to the message.
      *
      * @param contactsDevice device of the recipient
+     *
      * @throws NoIdentityKeyException if we have no identityKey of that device. Can be fixed by fetching and
      *                                processing the devices bundle.
      * @throws CorruptedOmemoKeyException if the identityKey of that device is corrupted.
@@ -248,7 +246,7 @@ public class OmemoMessageBuilder<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
     /**
      * Assemble an OmemoMessageElement from the current state of the builder.
      *
-     * @return OmemoMessageElement TODO javadoc me please
+     * @return OMEMO element
      */
     public OmemoElement finish() {
         OmemoHeaderElement_VAxolotl header = new OmemoHeaderElement_VAxolotl(
@@ -265,6 +263,7 @@ public class OmemoMessageBuilder<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
      * @param keyType Key Type
      * @param keyLength Key Length in bit
      * @return new AES key
+     *
      * @throws NoSuchAlgorithmException if no such algorithm is available.
      */
     public static byte[] generateKey(String keyType, int keyLength) throws NoSuchAlgorithmException {
@@ -276,7 +275,7 @@ public class OmemoMessageBuilder<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_
     /**
      * Generate a 12 byte initialization vector for AES encryption.
      *
-     * @return iv initialization vector
+     * @return initialization vector
      */
     public static byte[] generateIv() {
         SecureRandom random = new SecureRandom();