Class javadoc

code/Common/Aggregator.java

@@ -26,6 +26,13 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
+ * Aggregates a stream of classifications and performs averaging in order to
+ * smooth out results. Each classification supplied to the aggregator is used
+ * to alter the 'probabilities' of that classification holding. These
+ * probabilities are calculated hierarchically, and the aggregator can in some
+ * cases produce a result that is not in itself a normal activity because of
+ * this (for example, it may classify unclear data as
+ * <code>CLASSIFIED/VEHICLE</code>, rather than as a sub-type as expected).
  *
  * @author chris
  */

code/Common/BaseFactory.java

@@ -25,6 +25,8 @@ package uk.co.md87.android.common;
 import android.os.Build;
 
 /**
+ * Base class for sensor factory which facilitates switching to fake sources
+ * when running from an emulator.
  *
  * @author chris
  */

code/Common/Classifier.java

@@ -27,7 +27,11 @@ import java.util.Map.Entry;
 import java.util.Set;
 
 /**
- *
+ * Extracts basic features and applies a K-Nearest Network algorithm to an
+ * array of data in order to determine the classification. The data consists
+ * of two interleaved data sets, and each set has two features extracted -
+ * the range and the mean.
+ * 
  * @author chris
  */
 public class Classifier {

code/Common/ExceptionHandler.java

@@ -38,6 +38,8 @@ import org.apache.http.message.BasicNameValuePair;
 import org.apache.http.protocol.HTTP;
 
 /**
+ * An exception handler which reports any uncaught exceptions to the context
+ * API's website, in order to facilitate remote diagnostics of user errors.
  *
  * @author chris
  */
@@ -47,10 +49,6 @@ public class ExceptionHandler implements UncaughtExceptionHandler {
 
     private String appname, url, version, imei;
 
-    /*
-     * if any of the parameters is null, the respective functionality
-     * will not be used
-     */
     public ExceptionHandler(String appname, String url, String version, String imei) {
         this.appname = appname;
         this.url = url;
@@ -85,11 +83,10 @@ public class ExceptionHandler implements UncaughtExceptionHandler {
         nvps.add(new BasicNameValuePair("filename", filename));
         nvps.add(new BasicNameValuePair("stacktrace", stacktrace));
         try {
-            httpPost.setEntity(
-                    new UrlEncodedFormEntity(nvps, HTTP.UTF_8));
+            httpPost.setEntity(new UrlEncodedFormEntity(nvps, HTTP.UTF_8));
             httpClient.execute(httpPost);
         } catch (IOException e) {
-            e.printStackTrace();
+            // Do nothing
         }
     }
 }

code/Common/ModelReader.java

@@ -30,6 +30,8 @@ import java.io.ObjectInputStream;
 import java.util.Map;
 
 /**
+ * Provides a static method to read model data stored in a 'raw' resource
+ * as a serialised map.
  *
  * @author chris
  */

code/Common/accel/AccelReader.java

@@ -23,7 +23,8 @@
 package uk.co.md87.android.common.accel;
 
 /**
- *
+ * Interface implemented by classes which can sample accelerometer data.
+ * 
  * @author chris
  */
 public interface AccelReader {

code/Common/accel/AccelReaderFactory.java

@@ -25,6 +25,7 @@ package uk.co.md87.android.common.accel;
 import android.content.Context;
 
 /**
+ * A factory which can produce an appropriate {@link AccelReader}.
  *
  * @author chris
  */

code/Common/accel/RealAccelReader.java

@@ -30,6 +30,8 @@ import android.hardware.SensorManager;
 import android.os.PowerManager;
 
 /**
+ * An accelerometer reader which reads real data from the device's
+ * accelerometer.
  *
  * @author chris
  */

code/Common/accel/Sampler.java

@@ -25,6 +25,10 @@ package uk.co.md87.android.common.accel;
 import android.os.Handler;
 
 /**
+ * A utility class which handles sampling accelerometer data from an
+ * {@link AccelReader}. The Sampler takes 128 samples with a 50ms delay between
+ * each sample. When the Sampler has finished, it executes a runnable so that
+ * the data may be retrieved and analysed.
  *
  * @author chris
  */

code/Common/geo/FakeLocationMonitor.java

@@ -23,7 +23,8 @@
 package uk.co.md87.android.common.geo;
 
 /**
- *
+ * A dummy location monitor for use in emulator testing.
+ * 
  * @author chris
  */
 public class FakeLocationMonitor implements LocationMonitor {

code/Common/geo/LocationMonitor.java

@@ -23,7 +23,8 @@
 package uk.co.md87.android.common.geo;
 
 /**
- *
+ * Interface implemented by classes which can monitor the user's location.
+ * 
  * @author chris
  */
 public interface LocationMonitor {

code/Common/geo/LocationMonitorFactory.java

@@ -26,7 +26,8 @@ import android.content.Context;
 import uk.co.md87.android.common.BaseFactory;
 
 /**
- *
+ * A factory which can create relevant {@link LocationMonitor} instances.
+ * 
  * @author chris
  */
 public class LocationMonitorFactory extends BaseFactory {

code/Common/geo/RealLocationMonitor.java

@@ -29,6 +29,8 @@ import android.location.LocationManager;
 import android.os.Bundle;
 
 /**
+ * A {@link LocationMonitor} implementation that uses the device's coarse
+ * (network) location provider as a data source.
  *
  * @author chris
  */

code/ContextAnalyser/src/uk/co/md87/android/contextanalyser/ContextAnalyserService.java

@@ -46,6 +46,9 @@ import uk.co.md87.android.common.geo.LocationMonitor;
 import uk.co.md87.android.common.geo.LocationMonitorFactory;
 
 /**
+ * Background service which monitors and aggregates various sources of
+ * contextual information, including current activity and place. Changes in
+ * activity or other context cause the service to emit a broadcast Intent.
  *
  * @author chris
  */

code/ContextAnalyser/src/uk/co/md87/android/contextanalyser/DataHelper.java

@@ -34,6 +34,7 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
+ * Facilitates accessing the SQLite database used for storing places.
  *
  * @author chris
  */

code/ContextAnalyser/src/uk/co/md87/android/contextanalyser/Place.java

@@ -23,7 +23,9 @@
 package uk.co.md87.android.contextanalyser;
 
 /**
- *
+ * A place is a named location which has some significance for the user. Most
+ * places come about when the user remains stationary for a period of time.
+ * 
  * @author chris
  */
 public class Place {