Merge pull request #20 from optimizely/javadoc

Javadoc

Author: jophde

.idea/inspectionProfiles/Project_Default.xml

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2016, Optimizely
+ * <p/>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p/>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p/>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 apply plugin: 'com.android.library'
 apply plugin: 'maven'
 apply plugin: 'maven-publish'
@@ -53,6 +69,7 @@ dependencies {
 }
 
 uploadArchives {
+    dependsOn = [':android-sdk:clean', ':android-sdk:releaseJavadoc']
     shouldRunAfter = [':event-handler:uploadArchives', ':user-experiment-record:uploadArchives']
     repositories {
         mavenDeployer {
@@ -63,3 +80,34 @@ uploadArchives {
         }
     }
 }
+
+android.libraryVariants.all { variant ->
+    task("${variant.name}Javadoc", type: Javadoc, dependsOn: "assemble${variant.name.capitalize()}") {
+        source = variant.javaCompile.source
+
+        title = "Optimizely X Android SDK"
+
+        options.links("http://docs.oracle.com/javase/7/docs/api/");
+        options.linksOffline("http://d.android.com/reference", "${android.sdkDirectory}/docs/reference");
+
+        // First add all of your dependencies to the classpath, then add the android jars
+        classpath += files(variant.javaCompile.classpath.files)
+        classpath += files(android.getBootClasspath())
+
+        // We're excluding these generated files
+        exclude '**/BuildConfig.java'
+        exclude '**/R.java'
+
+        options.tags = ["hide"]
+    }
+}
+
+android.libraryVariants.all { variant ->
+    task("${variant.name}JavadocJar", type: Jar, dependsOn: "${variant.name}Javadoc") {
+        classifier = 'javadoc'
+        from tasks["${variant.name}Javadoc"].destinationDir
+    }
+
+    // Add the Javadoc jar to the project's artifacts. This will allow us to upload it easily later
+    project.artifacts.add("archives", tasks["${variant.name}JavadocJar"]);
+}

android-sdk/build.gradle

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package com.optimizely.ab.android.sdk;
 
 import android.app.Activity;
@@ -21,13 +22,10 @@
 
 import com.optimizely.ab.Optimizely;
 import com.optimizely.ab.UnknownEventTypeException;
-import com.optimizely.ab.UnknownExperimentException;
 import com.optimizely.ab.config.Experiment;
-import com.optimizely.ab.config.ProjectConfig;
 import com.optimizely.ab.config.Variation;
 
 import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
 import java.util.Map;
 
@@ -52,10 +50,14 @@ public class AndroidOptimizely {
     }
 
     /**
+     * Activate an experiment for a user
      * @see Optimizely#activate(String, String)
+     * @param experimentKey the experiment key
+     * @param userId the user id
+     * @return the {@link Variation} the user bucketed into
      */
     public @Nullable Variation activate(@NonNull String experimentKey,
-                       @NonNull String userId) throws UnknownExperimentException {
+                                        @NonNull String userId) {
         if (optimizely != null) {
             return optimizely.activate(experimentKey, userId);
         } else {
@@ -66,11 +68,17 @@ public class AndroidOptimizely {
     }
 
     /**
-     * @see Optimizely#activate(String, String, Map)
+     * Activate an experiment for a user
+     * @see Optimizely#activate(String, String)
+     * @param experimentKey the experiment key
+     * @param userId the user id
+     * @param attributes a map of attributes about the user
+     * @return the {@link Variation} the user bucketed into
      */
+    @SuppressWarnings("WeakerAccess")
     public @Nullable Variation activate(@NonNull String experimentKey,
                                         @NonNull String userId,
-                                        @NonNull Map<String, String> attributes) throws UnknownExperimentException {
+                                        @NonNull Map<String, String> attributes) {
         if (optimizely != null) {
             return optimizely.activate(experimentKey, userId, attributes);
         } else {
@@ -81,37 +89,12 @@ public class AndroidOptimizely {
     }
 
     /**
-     * @see Optimizely#activate(Experiment, String)
-     */
-    public @Nullable Variation activate(@NonNull Experiment experiment,
-                                        @NonNull String userId) {
-        if (optimizely != null) {
-            return optimizely.activate(experiment, userId);
-        } else {
-            logger.warn("Optimizely is not initialized, can't activate experiment {} for user {}",
-                    experiment.getKey(), userId);
-            return null;
-        }
-    }
-
-    public @Nullable Variation activate(@NonNull Experiment experiment,
-                                        @NonNull String userId,
-                                        @NonNull Map<String, String> attributes) {
-        if (optimizely != null) {
-            return optimizely.activate(experiment, userId, attributes);
-        } else {
-            logger.warn("Optimizely is not initialized, can't activate experiment {} for user {} " +
-                    "with attributes", experiment.getKey(), userId);
-            return null;
-        }
-    }
-
-
-    /**
-     * @see Optimizely#track(String, String)
+     * Track an event for a user
+     * @param eventName the name of the event
+     * @param userId the user id
      */
     public void track(@NonNull String eventName,
-                      @NonNull String userId) throws UnknownEventTypeException {
+                      @NonNull String userId) {
         if (optimizely != null) {
             optimizely.track(eventName, userId);
         } else {
@@ -120,7 +103,10 @@ public void track(@NonNull String eventName,
     }
 
     /**
-     * @see Optimizely#track(String, String, Map)
+     * Track an event for a user
+     * @param eventName the name of the event
+     * @param userId the user id
+     * @param attributes a map of attributes about the user
      */
     public void track(@NonNull String eventName,
                       @NonNull String userId,
@@ -134,7 +120,10 @@ public void track(@NonNull String eventName,
     }
 
     /**
-     * @see Optimizely#track(String, String, long)
+     * Track an event for a user
+     * @param eventName the name of the event
+     * @param userId the user id
+     * @param eventValue a value to tie to the event
      */
     public void track(@NonNull String eventName,
                       @NonNull String userId,
@@ -148,12 +137,17 @@ public void track(@NonNull String eventName,
     }
 
     /**
-     * @see Optimizely#track(String, String, Map, long)
+     * Track an event for a user with attributes and a value
+     * @see Optimizely#track(String, String, Map, Long)
+     * @param eventName the String name of the event
+     * @param userId the String user id
+     * @param attributes the attributes of the event
+     * @param eventValue the value of the event
      */
     public void track(@NonNull String eventName,
                       @NonNull String userId,
                       @NonNull Map<String, String> attributes,
-                      long eventValue) throws UnknownEventTypeException {
+                      long eventValue) {
         if (optimizely != null) {
             optimizely.track(eventName, userId, attributes, eventValue);
         } else {
@@ -162,26 +156,16 @@ public void track(@NonNull String eventName,
         }
     }
 
-
     /**
+     * Get the variation the user is bucketed into
      * @see Optimizely#getVariation(Experiment, String)
+     * @param experimentKey a String experiment key
+     * @param userId a String user id
+     * @return a variation for the provided experiment key and user id
      */
-    public @Nullable Variation getVariation(@NonNull Experiment experiment,
-                                            @NonNull String userId) throws UnknownExperimentException {
-        if (optimizely != null) {
-            return optimizely.getVariation(experiment, userId);
-        } else {
-            logger.warn("Optimizely is not initialized, could not get variation for experiment {} " +
-                    "for user {}", experiment.getKey(), userId);
-            return null;
-        }
-    }
-
-    /**
-     * @see Optimizely#getVariation(String, String)
-     */
+    @SuppressWarnings("WeakerAccess")
     public @Nullable Variation getVariation(@NonNull String experimentKey,
-                                            @NonNull String userId) throws UnknownExperimentException{
+                                            @NonNull String userId) {
         if (optimizely != null) {
             return optimizely.getVariation(experimentKey, userId);
         } else {
@@ -192,8 +176,14 @@ public void track(@NonNull String eventName,
     }
 
     /**
-     * @see Optimizely#getVariation(String, String, Map)
+     * Get the variation the user is bucketed into
+     * @see Optimizely#getVariation(Experiment, String)
+     * @param experimentKey a String experiment key
+     * @param userId a String userId
+     * @param attributes a map of attributes
+     * @return the variation for the provided experiment key, user id, and attributes
      */
+    @SuppressWarnings("WeakerAccess")
     public @Nullable Variation getVariation(@NonNull String experimentKey,
                                             @NonNull String userId,
                                             @NonNull Map<String, String> attributes) {

android-sdk/src/main/java/com/optimizely/ab/android/sdk/AndroidOptimizely.java

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package com.optimizely.ab.android.sdk;
 
 import android.support.annotation.NonNull;
@@ -30,7 +31,7 @@
 import java.util.Iterator;
 import java.util.List;
 
-/**
+/*
  * Caches a json dict that saves state about which project IDs have background watching enabled.
  */
 class BackgroundWatchersCache {

android-sdk/src/main/java/com/optimizely/ab/android/sdk/BackgroundWatchersCache.java

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package com.optimizely.ab.android.sdk;
 
 import android.support.annotation.NonNull;
@@ -27,7 +28,7 @@
 import java.io.FileNotFoundException;
 import java.io.IOException;
 
-/**
+/*
  * Abstracts the actual data "file" {@link java.io.File}
  */
 class DataFileCache {

android-sdk/src/main/java/com/optimizely/ab/android/sdk/DataFileCache.java

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package com.optimizely.ab.android.sdk;
 
 import android.support.annotation.NonNull;
@@ -25,7 +26,7 @@
 import java.net.HttpURLConnection;
 import java.net.URL;
 
-/**
+/*
  * Makes requests to the Optly CDN to get the data file
  */
 class DataFileClient {

android-sdk/src/main/java/com/optimizely/ab/android/sdk/DataFileClient.java

@@ -13,9 +13,21 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package com.optimizely.ab.android.sdk;
 
+/**
+ * Listens for new Optimizely datafiles
+ *
+ * @hide
+ */
 interface DataFileLoadedListener {
 
+    /**
+     * Called with new datafile
+     *
+     * @param dataFile the datafile json
+     * @hide
+     */
     void onDataFileLoaded(String dataFile);
 }

android-sdk/src/main/java/com/optimizely/ab/android/sdk/DataFileLoadedListener.java

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package com.optimizely.ab.android.sdk;
 
 import android.os.AsyncTask;
@@ -30,7 +31,7 @@
 import java.util.concurrent.Executor;
 import java.util.concurrent.Executors;
 
-/**
+/*
  * Handles intents and bindings in {@link DataFileService}
  */
 class DataFileLoader {

android-sdk/src/main/java/com/optimizely/ab/android/sdk/DataFileLoader.java

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package com.optimizely.ab.android.sdk;
 
 import android.content.BroadcastReceiver;
@@ -27,6 +28,12 @@
 
 import java.util.List;
 
+/**
+ * Broadcast Receiver that handles app upgrade and phone restart broadcasts in order
+ * to reschedule {@link DataFileService}
+ *
+ * @hide
+ */
 public class DataFileRescheduler extends BroadcastReceiver {
     Logger logger = LoggerFactory.getLogger(DataFileRescheduler.class);
 
@@ -49,7 +56,7 @@ public void onReceive(Context context, Intent intent) {
         }
     }
 
-    /**
+    /*
      * Handles building sending Intents to {@link DataFileService}
      *
      * This abstraction mostly makes unit testing easier