From a8b2446042f987f1881f1b3cf4db20a01aabb800 Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Fri, 13 Dec 2019 18:25:46 +0100 Subject: [PATCH] Fix javadoc issues --- .../omemo/signal/SignalOmemoRatchet.java | 1 - .../signal/SignalOmemoStoreConnector.java | 5 ++- .../smackx/omemo/CachingOmemoStore.java | 16 ++++---- .../smackx/omemo/FileBasedOmemoStore.java | 3 +- .../smackx/omemo/OmemoConfiguration.java | 8 ++-- .../smackx/omemo/OmemoInitializer.java | 2 +- .../smackx/omemo/OmemoManager.java | 34 ++++++++------- .../smackx/omemo/OmemoMessage.java | 8 ++-- .../smackx/omemo/OmemoService.java | 41 ++++++++++--------- .../jivesoftware/smackx/omemo/OmemoStore.java | 26 ++++++++---- .../omemo/element/OmemoBundleElement.java | 2 +- .../element/OmemoBundleElement_VAxolotl.java | 5 ++- .../smackx/omemo/element/OmemoElement.java | 2 +- .../CannotEstablishOmemoSessionException.java | 3 +- .../MultipleCryptoFailedException.java | 3 -- .../exceptions/ReadOnlyDeviceException.java | 3 +- .../exceptions/StaleDeviceException.java | 4 +- .../omemo/internal/CiphertextTuple.java | 4 +- .../smackx/omemo/internal/OmemoDevice.java | 4 +- .../smackx/omemo/trust/TrustState.java | 15 +++++-- .../smackx/omemo/util/OmemoConstants.java | 1 - .../smackx/omemo/util/OmemoKeyUtil.java | 23 +++++++---- .../omemo/util/OmemoMessageBuilder.java | 11 ++--- 23 files changed, 126 insertions(+), 98 deletions(-) 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..780951243 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 @@ -437,8 +437,9 @@ public class CachingOmemoStore getCache(OmemoDevice device) { KeyCache cache = caches.get(device); @@ -451,11 +452,12 @@ public class CachingOmemoStore - * @param - * @param - * @param - * @param + * + * @param type of the identity key pair + * @param type of the public identity key + * @param type of a public preKey + * @param type of the public signed preKey + * @param type of the OMEMO session */ private static class KeyCache { 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 FileBasedOmemoStoreBlog Post explaining the danger of read-only devices. TODO: Add URL + * @see Blog Post explaining the danger of read-only devices. */ 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 Blog Post explaining the danger of read-only devices. TODO: Add URL + * @see Blog Post explaining the danger of read-only devices. */ 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 Blog Post explaining the danger of read-only devices. TODO: Add URL + * @see Blog Post explaining the danger of read-only devices. */ 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 Blog Post explaining the danger of read-only devices. TODO: Add URL + * @see Blog Post explaining the danger of read-only devices. */ 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..71d80d478 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 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; @@ -530,10 +531,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, @@ -564,7 +566,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 +583,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. @@ -763,7 +768,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 +778,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 +791,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 +800,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(); @@ -926,7 +932,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(); 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..a1486d900 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 (<encrypted/>). * - * @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() { @@ -189,7 +190,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; 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 372579b61..f9a01f108 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 @@ -107,17 +107,11 @@ public abstract class OmemoService INSTANCE; private OmemoStore omemoStore; private final HashMap> omemoRatchets = new HashMap<>(); - /** - * Create a new OmemoService object. This should only happen once. - */ protected OmemoService() { } @@ -229,7 +223,7 @@ public abstract class OmemoService decryptMamQueryResult(OmemoManager.LoggedInOmemoManager managerGuard, @@ -1326,8 +1325,10 @@ public abstract class OmemoService getPreKeys() { if (preKeys == null) { 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 XEP-0384: OMEMO Encryption (Example 3). * * @author Paul Schaub */ 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> 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 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..d3110f0a8 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; 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/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..f72630bac 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 @@ -22,7 +22,6 @@ package org.jivesoftware.smackx.omemo.util; */ 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..163fb06cf 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 ratchet, String message) throws NoSuchPaddingException, BadPaddingException, InvalidKeyException, NoSuchAlgorithmException, IllegalBlockSizeException, - UnsupportedEncodingException, InvalidAlgorithmParameterException { + InvalidAlgorithmParameterException { this(userDevice, callback, ratchet, generateKey(KEYTYPE, KEYLENGTH), generateIv(), message); } @@ -148,7 +144,6 @@ public class OmemoMessageBuilder