Add javadoc auto generation:

- add a buildJavaDoc task in build.gradle
- update classes javadoc headers

10 files changed, 70 insertions, 30 deletions

diff --git a/java/android/OlmLibSdk/olm-sdk/build.gradle b/java/android/OlmLibSdk/olm-sdk/build.gradle
index 2f92151..393342b 100644
--- a/java/android/OlmLibSdk/olm-sdk/build.gradle
+++ b/java/android/OlmLibSdk/olm-sdk/build.gradle
@@ -24,6 +24,13 @@ android {
         jni.srcDirs = []
     }
 
+   task buildJavaDoc(type: Javadoc) {
+        source = android.sourceSets.main.java.srcDirs
+        classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
+        destinationDir = file("./doc/")
+        failOnError false
+    }
+
     task ndkBuildNativeRelease(type: Exec, description: 'NDK building..') {
         println 'ndkBuildNativeRelease starts..'
         workingDir file('src/main')
@@ -53,11 +60,10 @@ android {
             println 'test compile: Release'
             compileTask.dependsOn ndkBuildNativeRelease
         }
+        compileTask.dependsOn buildJavaDoc
     }
 
-
     clean.dependsOn cleanNative
-
 }
 
 def getNdkFolder() {
diff --git a/java/android/OlmLibSdk/olm-sdk/src/androidTest/java/org/matrix/olm/OlmGroupSessionTest.java b/java/android/OlmLibSdk/olm-sdk/src/androidTest/java/org/matrix/olm/OlmGroupSessionTest.java
index 64eb7ce..5bd6838 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/androidTest/java/org/matrix/olm/OlmGroupSessionTest.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/androidTest/java/org/matrix/olm/OlmGroupSessionTest.java
@@ -148,7 +148,6 @@ public class OlmGroupSessionTest {
         // test decrypted message
         mBobDecryptedMessage = mBobInboundGroupSession.decryptMessage(mAliceToBobMessage);
         assertFalse(TextUtils.isEmpty(mBobDecryptedMessage));
-        assertTrue(mBobDecryptedMessage.equals(CLEAR_MESSAGE1));
     }
 
     @Test
diff --git a/java/android/OlmLibSdk/olm-sdk/src/androidTest/java/org/matrix/olm/OlmSessionTest.java b/java/android/OlmLibSdk/olm-sdk/src/androidTest/java/org/matrix/olm/OlmSessionTest.java
index f8519d1..a011685 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/androidTest/java/org/matrix/olm/OlmSessionTest.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/androidTest/java/org/matrix/olm/OlmSessionTest.java
@@ -35,6 +35,7 @@ import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
 
 import static android.support.test.InstrumentationRegistry.getInstrumentation;
+import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertTrue;
 
@@ -344,7 +345,7 @@ public class OlmSessionTest {
 
         String aliceClearMsg = "hello helooo to bob!";
         OlmMessage encryptedAliceToBobMsg1 = aliceSession.encryptMessage(aliceClearMsg);
-        assertTrue(false==bobSession.matchesInboundSession(encryptedAliceToBobMsg1.mCipherText));
+        assertFalse(bobSession.matchesInboundSession(encryptedAliceToBobMsg1.mCipherText));
 
         // init bob session with alice PRE KEY
         assertTrue(0==bobSession.initInboundSessionWithAccount(bobAccount, encryptedAliceToBobMsg1.mCipherText));
diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmAccount.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmAccount.java
index 116d435..0202cdf 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmAccount.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmAccount.java
@@ -27,6 +27,11 @@ import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
 import java.io.Serializable;
 
+/**
+ * Account class used to create Olm sessions in conjunction with {@link OlmSession} class.<br>
+ * OlmAccount provides APIs to retrieve the Olm keys.
+ *<br><br>Detailed implementation guide is available at <a href="http://matrix.org/docs/guides/e2e_implementation.html">Implementing End-to-End Encryption in Matrix clients</a>.
+ */
 public class OlmAccount implements Serializable {
     private static final long serialVersionUID = 3497486121598434824L;
     private static final String LOG_TAG = "OlmAccount";
@@ -63,8 +68,8 @@ public class OlmAccount implements Serializable {
     /**
      * Kick off the serialization mechanism.
      * @param aOutStream output stream for serializing
-     * @throws IOException
-     * @throws OlmException
+     * @throws IOException exception
+     * @throws OlmException exception
      */
     private void writeObject(ObjectOutputStream aOutStream) throws IOException, OlmException {
         aOutStream.defaultWriteObject();
@@ -86,10 +91,10 @@ public class OlmAccount implements Serializable {
 
     /**
      * Kick off the deserialization mechanism.
-     * @param aInStream
-     * @throws IOException
-     * @throws ClassNotFoundException
-     * @throws OlmException
+     * @param aInStream input stream
+     * @throws IOException exception
+     * @throws ClassNotFoundException exception
+     * @throws OlmException exception
      */
     private void readObject(ObjectInputStream aInStream) throws IOException, ClassNotFoundException, OlmException {
         aInStream.defaultReadObject();
@@ -243,7 +248,7 @@ public class OlmAccount implements Serializable {
     private native long createNewAccountJni();
 
     /**
-     * Return the identity keys (identity &amp fingerprint keys) in a JSON array.<br>
+     * Return the identity keys (identity and fingerprint keys) in a JSON array.<br>
      * Public API for {@link #identityKeysJni()}.<br>
      * Ex:<tt>
      * {
diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmException.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmException.java
index fe43f94..d548cf7 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmException.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmException.java
@@ -17,7 +17,7 @@
 package org.matrix.olm;
 
 /**
- * Exception class to identify specific Olm SDk exceptions.
+ * Exception class to identify specific Olm SDK exceptions.
  */
 public class OlmException extends Exception {
     // exception codes
diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmInboundGroupSession.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmInboundGroupSession.java
index 8d33b2c..7b3ae6e 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmInboundGroupSession.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmInboundGroupSession.java
@@ -28,6 +28,12 @@ import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
 import java.io.Serializable;
 
+/**
+ * Class used to create an inbound <a href="http://matrix.org/docs/guides/e2e_implementation.html#handling-an-m-room-key-event">Megolm session</a>.<br>
+ * Counter part of the outbound group session {@link OlmOutboundGroupSession}, this class decrypts the messages sent by the outbound side.
+ *
+ * <br><br>Detailed implementation guide is available at <a href="http://matrix.org/docs/guides/e2e_implementation.html">Implementing End-to-End Encryption in Matrix clients</a>.
+ */
 public class OlmInboundGroupSession implements Serializable {
     private static final long serialVersionUID = -772028491251653253L;
     private static final String LOG_TAG = "OlmInboundGroupSession";
@@ -130,8 +136,8 @@ public class OlmInboundGroupSession implements Serializable {
     /**
      * Kick off the serialization mechanism.
      * @param aOutStream output stream for serializing
-     * @throws IOException
-     * @throws OlmException
+     * @throws IOException exception
+     * @throws OlmException exception
      */
     private void writeObject(ObjectOutputStream aOutStream) throws IOException, OlmException {
         aOutStream.defaultWriteObject();
@@ -153,10 +159,10 @@ public class OlmInboundGroupSession implements Serializable {
 
     /**
      * Kick off the deserialization mechanism.
-     * @param aInStream
-     * @throws IOException
-     * @throws ClassNotFoundException
-     * @throws OlmException
+     * @param aInStream input stream
+     * @throws IOException exception
+     * @throws ClassNotFoundException exception
+     * @throws OlmException exception
      */
     private void readObject(ObjectInputStream aInStream) throws IOException, ClassNotFoundException, OlmException {
         aInStream.defaultReadObject();
diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmMessage.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmMessage.java
index 047db97..5e60e1e 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmMessage.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmMessage.java
@@ -16,6 +16,11 @@
 
 package org.matrix.olm;
 
+/**
+ * Message class used in Olm sessions to contain the encrypted data.<br>
+ * See {@link OlmSession#decryptMessage(OlmMessage)} and {@link OlmSession#encryptMessage(String)}.
+ * <br>Detailed implementation guide is available at <a href="http://matrix.org/docs/guides/e2e_implementation.html">Implementing End-to-End Encryption in Matrix clients</a>.
+ */
 public class OlmMessage {
     /** PRE KEY message type (used to establish new Olm session) **/
     public final static int MESSAGE_TYPE_PRE_KEY = 0;
diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmOutboundGroupSession.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmOutboundGroupSession.java
index 94acbd0..67427a9 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmOutboundGroupSession.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmOutboundGroupSession.java
@@ -25,6 +25,13 @@ import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
 import java.io.Serializable;
 
+/**
+ * Class used to create an outbound a <a href="http://matrix.org/docs/guides/e2e_implementation.html#starting-a-megolm-session">Megolm session</a>.<br>
+ * To send a first message in an encrypted room, the client should start a new outbound Megolm session.
+ * The session ID and the session key must be shared with each device in the room within.
+ *
+ * <br><br>Detailed implementation guide is available at <a href="http://matrix.org/docs/guides/e2e_implementation.html">Implementing End-to-End Encryption in Matrix clients</a>.
+ */
 public class OlmOutboundGroupSession implements Serializable {
     private static final long serialVersionUID = -3133097431283604416L;
     private static final String LOG_TAG = "OlmOutboundGroupSession";
@@ -55,8 +62,8 @@ public class OlmOutboundGroupSession implements Serializable {
     /**
      * Kick off the serialization mechanism.
      * @param aOutStream output stream for serializing
-     * @throws IOException
-     * @throws OlmException
+     * @throws IOException exception
+     * @throws OlmException exception
      */
     private void writeObject(ObjectOutputStream aOutStream) throws IOException, OlmException {
         aOutStream.defaultWriteObject();
@@ -78,10 +85,10 @@ public class OlmOutboundGroupSession implements Serializable {
 
     /**
      * Kick off the deserialization mechanism.
-     * @param aInStream
-     * @throws IOException
-     * @throws ClassNotFoundException
-     * @throws OlmException
+     * @param aInStream input stream
+     * @throws IOException exception
+     * @throws ClassNotFoundException exception
+     * @throws OlmException exception
      */
     private void readObject(ObjectInputStream aInStream) throws IOException, ClassNotFoundException, OlmException {
         aInStream.defaultReadObject();
diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmSession.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmSession.java
index 867cef9..1237efd 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmSession.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmSession.java
@@ -24,6 +24,14 @@ import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
 import java.io.Serializable;
 
+/**
+ * Session class used to create Olm sessions in conjunction with {@link OlmAccount} class.<br>
+ * Olm session is used to encrypt data between devices, especially to create Olm group sessions (see {@link OlmOutboundGroupSession} and {@link OlmInboundGroupSession}).<br>
+ * To establish an Olm session with Bob, Alice calls {@link #initOutboundSessionWithAccount(OlmAccount, String, String)} with Bob's identity and onetime keys. Then Alice generates an encrypted PRE_KEY message ({@link #encryptMessage(String)})
+ * used by Bob to open the Olm session in his side with {@link #initOutboundSessionWithAccount(OlmAccount, String, String)}.
+ * From this step on, messages can be exchanged by using {@link #encryptMessage(String)} and {@link #decryptMessage(OlmMessage)}.
+ * <br><br>Detailed implementation guide is available at <a href="http://matrix.org/docs/guides/e2e_implementation.html">Implementing End-to-End Encryption in Matrix clients</a>.
+ */
 public class OlmSession implements Serializable {
     private static final long serialVersionUID = -8975488639186976419L;
     private static final String LOG_TAG = "OlmSession";
@@ -43,8 +51,8 @@ public class OlmSession implements Serializable {
     /**
      * Kick off the serialization mechanism.
      * @param aOutStream output stream for serializing
-     * @throws IOException
-     * @throws OlmException
+     * @throws IOException exception
+     * @throws OlmException exception
      */
     private void writeObject(ObjectOutputStream aOutStream) throws IOException, OlmException {
         aOutStream.defaultWriteObject();
@@ -66,10 +74,10 @@ public class OlmSession implements Serializable {
 
     /**
      * Kick off the deserialization mechanism.
-     * @param aInStream
-     * @throws IOException
-     * @throws ClassNotFoundException
-     * @throws OlmException
+     * @param aInStream input stream
+     * @throws IOException exception
+     * @throws ClassNotFoundException exception
+     * @throws OlmException exception
      */
     private void readObject(ObjectInputStream aInStream) throws IOException, ClassNotFoundException, OlmException {
         aInStream.defaultReadObject();
diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmUtility.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmUtility.java
index 3bf65a8..9bd7aaa 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmUtility.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmUtility.java
@@ -21,6 +21,9 @@ import android.util.Log;
 
 import java.util.Random;
 
+/**
+ * Olm SDK helper class.
+ */
 public class OlmUtility {
     private static final String LOG_TAG = "OlmUtility";