Merge pull request #22 from kissmetrics/kh/javadocs

Javadoc and Jar Automation

build.gradle

@@ -4,7 +4,7 @@ buildscript {
   }
 
   dependencies {
-    classpath 'com.android.tools.build:gradle:1.1.0'
+    classpath 'com.android.tools.build:gradle:1.1.+'
   }
 }
 
@@ -17,8 +17,8 @@ android {
   defaultConfig {
     minSdkVersion 8
     targetSdkVersion 22
-    versionCode 2
-    versionName "2.2.1"
+    versionCode 3
+    versionName "2.2.2"
   }
 
   buildTypes {
@@ -55,7 +55,8 @@ task wrapper(type: org.gradle.api.tasks.wrapper.Wrapper) {
   gradleVersion = '2.3'
 }
 
-// Take from http://stackoverflow.com/questions/19307341/android-library-gradle-release-jar/19484146#19484146
+// Take from
+// http://stackoverflow.com/questions/19307341/android-library-gradle-release-jar/19484146#19484146
 android.libraryVariants.all { variant ->
   def name = variant.buildType.name
 
@@ -66,5 +67,33 @@ android.libraryVariants.all { variant ->
   def task = project.tasks.create "jar${name.capitalize()}", Jar
   task.dependsOn variant.javaCompile
   task.from variant.javaCompile.destinationDir
-  artifacts.add('archives', task);
+  artifacts.add('archives', task)
+}
+
+// This magic came from:
+// http://stackoverflow.com/questions/23297562/gradle-javadoc-and-android-documentation
+task javadocs(type: Javadoc) {
+  title = "KISSmetrics Android API ${android.defaultConfig.versionName}"
+  description = 'Documentation for the KISSmetrics Android API'
+
+  def variant = android.libraryVariants.release
+  source = android.sourceSets.main.java.srcDirs
+  classpath = files(variant.javaCompile.classpath.files, project.android.getBootClasspath())
+  options {
+    links "http://docs.oracle.com/javase/7/docs/api/"
+    linksOffline "http://d.android.com/reference","${android.sdkDirectory}/docs/reference"
+  }
+
+  exclude '**/BuildConfig.java'
+  exclude '**/R.java'
+}
+
+task sourcesJar(type: Jar) {
+  classifier 'sources'
+  from android.sourceSets.main.java.srcDirs
+}
+
+task javadocsJar(type: Jar, dependsOn: javadocs) {
+  classifier 'javadoc'
+  from "${project.buildDir}/docs/javadoc"
 }

releasing.md

@@ -0,0 +1,51 @@
+# Releasing
+
+### 1. Make sure the tests run
+
+An important step many may forget:
+
+```sh
+gradle connectedAndroidTest
+```
+
+You will need an Android emulator running to run the tests.
+
+### 2. Bump Version Number
+
+The version number needs to be increased.  If it is a feature addition/change
+bump the second number (i.e. 2.X.0).  If it is a patch/bug fix bump the last
+number (i.e. 2.0.X).
+
+In the `build.gradle` file also bump the `versionCode` number by 1.  This is an
+Android thing.
+
+The version number lives in:
+
+  1. `Connection.java` under `com.kissmetrics.sdk`.  It's in the constant `USER_AGENT`
+  2. `build.gradle` file at the root.
+
+### 3. Merge and Tag
+
+Get your changes into the `master` branch.  Then create a tag with the version:
+
+### 4. Build Artifacts
+
+You can build everything you need with this command line and Gradle 2.3+:
+
+```sh
+gradle clean build compileReleaseSources javadocs javadocsJar sourcesJar
+```
+
+It will create the following files:
+
+```
+build/libs/KISSmetricsSDK-javadoc.jar
+build/libs/KISSmetricsSDK-sources.jar
+build/libs/KISSmetricsSDK.jar
+build/outputs/aar/KISSmetricsSDK-debug.aar
+build/outputs/aar/KISSmetricsSDK-release.aar
+```
+
+### 5. Release
+
+Create the Release on GitHub.

src/main/AndroidManifest.xml

@@ -1,8 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-          package="com.kissmetrics.sdk"
-          android:versionCode="2"
-          android:versionName="2.2.1">
+          package="com.kissmetrics.sdk">
 
     <uses-sdk android:minSdkVersion="7" android:targetSdkVersion="22"/>
 

src/main/java/com/kissmetrics/sdk/ArchiverImpl.java

@@ -33,8 +33,6 @@
 import android.util.Log;
 
 /**
- * ArchiverImpl
- * <p/>
  * Handles read/write of settings, identity, recorded events and properties.
  * Recorded events and properties are URL encoded before being saved to a send queue.
  */
@@ -408,7 +406,7 @@ private long currentTimeSeconds() {
    ************************************************/
 
   /**
-   * Archives install UUID to Settings > Internal Storage.
+   * Archives install UUID to Settings &lt; Internal Storage.
    *
    * @param installUuid Unique identifier of the application install which may only be
    *                    archived once.
@@ -430,7 +428,7 @@ public void archiveInstallUuid(final String installUuid) {
   }
 
   /**
-   * Archives doTrack boolean to Settings > Internal Storage.
+   * Archives doTrack boolean to Settings &lt; Internal Storage.
    *
    * @param doTrack Setting to control recording of aliases, events and properties.
    */
@@ -442,7 +440,7 @@ public void archiveDoTrack(boolean doTrack) {
   }
 
   /**
-   * Archives doSend boolean to Settings > Internal Storage.
+   * Archives doSend boolean to Settings &lt; Internal Storage.
    *
    * @param doSend Setting to control the uploading of aliases, events and properties.
    */
@@ -454,7 +452,7 @@ public void archiveDoSend(boolean doSend) {
   }
 
   /**
-   * Archives baseUrl String to Settings > Internal Storage.
+   * Archives baseUrl String to Settings &lt; Internal Storage.
    *
    * @param baseUrl Setting for API base URL path
    */
@@ -472,7 +470,7 @@ public void archiveBaseUrl(String baseUrl) {
   }
 
   /**
-   * Archives doTrack verification expiration date to Settings > Internal Storage.
+   * Archives doTrack verification expiration date to Settings &lt; Internal Storage.
    *
    * @param expDate Milliseconds from unix epoch when verification expires.
    */
@@ -484,7 +482,7 @@ public void archiveVerificationExpDate(long expDate) {
   }
 
   /**
-   * Archives hasGenericIdentity boolean to Settings > Internal Storage.
+   * Archives hasGenericIdentity boolean to Settings &lt; Internal Storage.
    *
    * @param hasGenericIdentity setting to indicate that a proper identity has been given.
    */
@@ -495,7 +493,7 @@ public void archiveHasGenericIdentity(final boolean hasGenericIdentity) {
   }
 
   /**
-   * Archives appVersion to Settings > Internal Storage.
+   * Archives appVersion to Settings &lt; Internal Storage.
    *
    * @param appVersion String app version name.
    */

src/main/java/com/kissmetrics/sdk/Connection.java

@@ -21,14 +21,14 @@
  * Connection interface
  */
 interface Connection {
-  public static final String USER_AGENT = "KISSmetrics-Android/2.2.1";
+  public static final String USER_AGENT = "KISSmetrics-Android/2.2.2";
 
   /**
    * Makes a request to the provided API query urlString.
    * Handles the response and notifies the provided ConnectionDelgate on completion.
    *
    * @param urlString URL encoded API query string
-   * @delegate delegate Object implementing the ConnectionDelegate interface
+   * @param delegate Object implementing the ConnectionDelegate interface
    */
   void sendRecord(String urlString, ConnectionDelegate delegate);
 }

src/main/java/com/kissmetrics/sdk/ConnectionImpl.java

@@ -26,8 +26,6 @@
 import android.util.Log;
 
 /**
- * ConnectionImpl
- * <p/>
  * Handles HttpURLConnections for KISSmetrics API queries.
  */
 public class ConnectionImpl implements Connection {
@@ -52,7 +50,7 @@ protected HttpURLConnection createHttpURLConnection(URL url) throws IOException
    * Handles the response and notifies the provided ConnectionDelgate on completion.
    *
    * @param urlString URL encoded API query string
-   * @delegate delegate Object implementing the ConnectionDelegate interface
+   * @param delegate Object implementing the ConnectionDelegate interface
    */
   public void sendRecord(String urlString, ConnectionDelegate delegate) {
     URL url = null;

src/main/java/com/kissmetrics/sdk/KISSmetricsAPI.java

@@ -27,8 +27,6 @@
 import android.util.Log;
 
 /**
- * KISSmetricsAPI
- * <p/>
  * Public API for sending identities, events and properties to KISSmetrics from
  * Android applications. Compatible with Android 2.2+
  */
@@ -66,7 +64,7 @@ protected static void setVerificationImpl(VerificationImpl verImpl) {
   /**
    * Initializes the default Connection if not set. Allows for injection of
    * mock HttpURLConnection within VerificationImpl.
-   * <p/>
+   *
    * Returns the injected verificationImpl if it exists.
    *
    * @return Connection
@@ -405,7 +403,7 @@ public void autoSetAppProperties() {
     }
   }
 
-  /**
+  /*
    * *********************************************
    * VerificationDelegateInterface methods
    * **********************************************
@@ -457,15 +455,16 @@ public void verificationComplete(boolean success,
    ************************************************/
 
   /**
+   * Initializes and/or returns the KISSmetricsAPI singleton
+   * instance.
+   *
    * @param apiKey  KISSmetrics product key
    * @param context Android application context
    * @param secure  !Ignored!
    * @return singleton instance of the KISSmeticsAPI
-   * @deprecated use {@link sharedAPI(String apiKey)} instead. All requests
+   *
+   * @deprecated use {@link #sharedAPI(String, android.content.Context)} instead. All requests
    * are now made over https. secure(boolean) is ignored.
-   * <p/>
-   * Initializes and/or returns the KISSmetricsAPI singleton
-   * instance.
    */
   @Deprecated
   public static synchronized KISSmetricsAPI sharedAPI(String apiKey,
@@ -478,13 +477,12 @@ public static synchronized KISSmetricsAPI sharedAPI(String apiKey,
   }
 
   /**
+   * Records an event with optional properties.
+   *
    * @param name       Event name
    * @param properties Event properties or null
-   * @deprecated use {@link record(String name, Map<String, String>
-   * properties)} instead. 'recordEvent' method name has been
-   * changed to 'record' for consistency across our various APIs.
-   * <p/>
-   * Records an event with optional properties.
+   * @deprecated use {@link #record(String, java.util.Map)} instead. 'recordEvent' method name
+   * has been changed to 'record' for consistency across our various APIs.
    */
   @Deprecated
   public void recordEvent(String name, Map<String, String> properties) {
@@ -493,11 +491,10 @@ public void recordEvent(String name, Map<String, String> properties) {
 
   /**
    * @param name Event name
-   * @deprecated use {@link record(String name, Map<String, String>
-   * properties), RecordCondition condition} instead. 'recordOnce'
-   * would only restrict the recording of events per identity. A
-   * more flexible solution was needed to allow recording of
-   * events once per installation or identity.
+   * @deprecated use {@link #record(String, java.util.Map, com.kissmetrics.sdk.KISSmetricsAPI.RecordCondition)}
+   * instead. 'recordOnce' would only restrict the recording of events per identity.  A
+   * more flexible solution was needed to allow recording of events once per installation or
+   * identity.
    */
   @Deprecated
   public void recordOnce(String name) {
@@ -507,9 +504,8 @@ public void recordOnce(String name) {
 
   /**
    * @param properties User properties
-   * @deprecated use {@link set(Map<String, String> properties)} instead.
-   * 'setProperties' method name has been changed to 'set' for
-   * consistency across our various APIs.
+   * @deprecated use {@link #set(java.util.Map)} instead. <tt>setProperties</tt> method name
+   * has been changed to 'set' for consistency across our various APIs.
    */
   @Deprecated
   public void setProperties(Map<String, String> properties) {

src/main/java/com/kissmetrics/sdk/QueryEncoder.java

@@ -25,8 +25,6 @@
 import android.util.Log;
 
 /**
- * QueryEncoder
- * <p/>
  * URL encoder for KISSmetricsAPI queries.
  */
 public class QueryEncoder {
@@ -51,7 +49,7 @@ public QueryEncoder(String key, String clientType, String userAgent) {
   }
 
   /**
-   * Checks provided properties HashMap for _d & _t timestamp keys.
+   * Checks provided properties HashMap for _d &amp; _t timestamp keys.
    *
    * @param properties HashMap of user or event properties
    * @return boolean  true if timestamp has been set in these properties
@@ -172,7 +170,7 @@ public String encodeProperties(Map<String, String> properties) {
    * @param name       Event name
    * @param properties Event properties
    * @param identity   User identity
-   * @param timestamp  A unix epoch timestamp to apply if _t & _d have not been set in properties
+   * @param timestamp  A unix epoch timestamp to apply if _t &amp; _d have not been set in properties
    * @return the URL encoded query string
    */
   public String createEventQuery(String name,
@@ -198,7 +196,7 @@ clientType, userAgent, encodeIdentity(identity),
    *
    * @param properties User properties
    * @param identity   User identity
-   * @param timestamp  A unix epoch timestamp to apply if _t & _d have not been set in properties
+   * @param timestamp  A unix epoch timestamp to apply if _t &amp; _d have not been set in properties
    * @return the URL encoded query string
    */
   public String createPropertiesQuery(Map<String, String> properties,

src/main/java/com/kissmetrics/sdk/TrackingRunnables.java

@@ -22,8 +22,6 @@
 import java.util.Map;
 
 /**
- * TrackingRunnables interface
- * <p/>
  * Classes implementing this interface provide Runnable objects to
  * handle tracking for specific tracking states.
  */

src/main/java/com/kissmetrics/sdk/TrackingRunnablesNonTrackingState.java

@@ -22,8 +22,6 @@
 import com.kissmetrics.sdk.KISSmetricsAPI.RecordCondition;
 
 /**
- * TrackingRunnables non-tracking state
- * <p/>
  * Provides Runnable objects for non-tracking state.
  */
 public class TrackingRunnablesNonTrackingState implements TrackingRunnables {

src/main/java/com/kissmetrics/sdk/TrackingRunnablesTrackingState.java

@@ -22,8 +22,6 @@
 import com.kissmetrics.sdk.KISSmetricsAPI.RecordCondition;
 
 /**
- * TrackingRunnables tracking state
- * <p/>
  * Provides Runnable objects for tracking state.
  */
 public class TrackingRunnablesTrackingState implements TrackingRunnables {

src/main/java/com/kissmetrics/sdk/package-info.java

@@ -0,0 +1,4 @@
+/**
+ *
+ */
+package com.kissmetrics.sdk;