Some Javadoc

app/src/main/java/nodomain/freeyourgadget/gadgetbridge/GBApplication.java

@@ -25,6 +25,10 @@ import nodomain.freeyourgadget.gadgetbridge.model.DeviceService;
 import nodomain.freeyourgadget.gadgetbridge.util.FileUtils;
 import nodomain.freeyourgadget.gadgetbridge.util.GB;
 
+/**
+ * Main Application class that initializes and provides access to certain things like
+ * logging and DB access.
+ */
 public class GBApplication extends Application {
     // Since this class must not log to slf4j, we use plain android.util.Log
     private static final String TAG = "GBApplication";
@@ -111,6 +115,12 @@ public class GBApplication extends Application {
         return context;
     }
 
+    /**
+     * Returns the facade for talking to devices. Devices are managed by
+     * an Android Service and this facade provides access to its functionality.
+     *
+     * @return the facade for talking to the service/devices.
+     */
     public static DeviceService deviceService() {
         return deviceService;
     }
@@ -152,14 +162,14 @@ public class GBApplication extends Application {
 
     public static HashSet<String> blacklist = null;
 
-    public static void loadBlackList() {
+    private static void loadBlackList() {
         blacklist = (HashSet<String>) sharedPrefs.getStringSet("package_blacklist", null);
         if (blacklist == null) {
             blacklist = new HashSet<>();
         }
     }
 
-    public static void saveBlackList() {
+    private static void saveBlackList() {
         SharedPreferences.Editor editor = sharedPrefs.edit();
         if (blacklist.isEmpty()) {
             editor.putStringSet("package_blacklist", null);

app/src/main/java/nodomain/freeyourgadget/gadgetbridge/GBEnvironment.java

@@ -1,5 +1,8 @@
 package nodomain.freeyourgadget.gadgetbridge;
 
+/**
+ * Some more or less useful utility methods to aid local (non-device) testing.
+ */
 public class GBEnvironment {
     private boolean localTest;
     private boolean deviceTest;

app/src/main/java/nodomain/freeyourgadget/gadgetbridge/LoggingExceptionHandler.java

@@ -4,6 +4,9 @@ package nodomain.freeyourgadget.gadgetbridge;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * Catches otherwise uncaught exceptions, logs them and terminates the app.
+ */
 public class LoggingExceptionHandler implements Thread.UncaughtExceptionHandler {
     private static final Logger LOG = LoggerFactory.getLogger(LoggingExceptionHandler.class);
     private final Thread.UncaughtExceptionHandler mDelegate;

app/src/main/java/nodomain/freeyourgadget/gadgetbridge/adapter/DeviceCandidateAdapter.java

@@ -15,6 +15,9 @@ import nodomain.freeyourgadget.gadgetbridge.impl.GBDevice;
 import nodomain.freeyourgadget.gadgetbridge.impl.GBDeviceCandidate;
 import nodomain.freeyourgadget.gadgetbridge.util.GB;
 
+/**
+ * Adapter for displaying GBDeviceCandate instances.
+ */
 public class DeviceCandidateAdapter extends ArrayAdapter<GBDeviceCandidate> {
 
     private final Context context;

app/src/main/java/nodomain/freeyourgadget/gadgetbridge/adapter/GBAlarmListAdapter.java

@@ -20,7 +20,9 @@ import nodomain.freeyourgadget.gadgetbridge.activities.ConfigureAlarms;
 import nodomain.freeyourgadget.gadgetbridge.impl.GBAlarm;
 import nodomain.freeyourgadget.gadgetbridge.model.Alarm;
 
-
+/**
+ * Adapter for displaying GBAlarm instances.
+ */
 public class GBAlarmListAdapter extends ArrayAdapter<GBAlarm> {
 
 

app/src/main/java/nodomain/freeyourgadget/gadgetbridge/adapter/GBDeviceAdapter.java

@@ -17,6 +17,9 @@ import nodomain.freeyourgadget.gadgetbridge.R;
 import nodomain.freeyourgadget.gadgetbridge.impl.GBDevice;
 import nodomain.freeyourgadget.gadgetbridge.model.BatteryState;
 
+/**
+ * Adapter for displaying GBDevice instances.
+ */
 public class GBDeviceAdapter extends ArrayAdapter<GBDevice> {
 
     private final Context context;

app/src/main/java/nodomain/freeyourgadget/gadgetbridge/adapter/GBDeviceAppAdapter.java

@@ -13,6 +13,9 @@ import java.util.List;
 import nodomain.freeyourgadget.gadgetbridge.R;
 import nodomain.freeyourgadget.gadgetbridge.impl.GBDeviceApp;
 
+/**
+ * Adapter for displaying GBDeviceApp instances.
+ */
 public class GBDeviceAppAdapter extends ArrayAdapter<GBDeviceApp> {
 
     private final Context context;

app/src/main/java/nodomain/freeyourgadget/gadgetbridge/adapter/ItemWithDetailsAdapter.java

@@ -13,6 +13,9 @@ import java.util.List;
 import nodomain.freeyourgadget.gadgetbridge.R;
 import nodomain.freeyourgadget.gadgetbridge.model.ItemWithDetails;
 
+/**
+ * Adapter for displaying generic ItemWithDetails instances.
+ */
 public class ItemWithDetailsAdapter extends ArrayAdapter<ItemWithDetails> {
 
     private final Context context;

app/src/main/java/nodomain/freeyourgadget/gadgetbridge/devices/DeviceCoordinator.java

@@ -8,26 +8,86 @@ import nodomain.freeyourgadget.gadgetbridge.impl.GBDevice;
 import nodomain.freeyourgadget.gadgetbridge.impl.GBDeviceCandidate;
 import nodomain.freeyourgadget.gadgetbridge.model.DeviceType;
 
+/**
+ * This interface is implemented at least once for every supported gadget device.
+ * It allows Gadgetbridge to generically deal with different kinds of devices
+ * without actually knowing the details of any device.
+ *
+ * Instances will be created as needed and asked whether they support a given
+ * device. If a coordinator answers true, it will be used to assist in handling
+ * the given device.
+ */
 public interface DeviceCoordinator {
     String EXTRA_DEVICE_MAC_ADDRESS = "nodomain.freeyourgadget.gadgetbridge.impl.GBDeviceCandidate.EXTRA_MAC_ADDRESS";
 
+    /**
+     * Checks whether this candidate handles the given candidate.
+     * @param candidate
+     * @return true if this coordinator handles the given candidate.
+     */
     boolean supports(GBDeviceCandidate candidate);
 
+    /**
+     * Checks whether this candidate handles the given device.
+     * @param device
+     * @return true if this coordinator handles the given device.
+     */
     boolean supports(GBDevice device);
 
+    /**
+     * Returns the kind of device type this coordinator supports.
+     * @return
+     */
     DeviceType getDeviceType();
 
+    /**
+     * Returns the Activity class to be started in order to perform a pairing of a
+     * given device.
+     * @return
+     */
     Class<? extends Activity> getPairingActivity();
 
+    /**
+     * Returns the Activity class that will be used as the primary activity
+     * for the given device.
+     * @return
+     */
     Class<? extends Activity> getPrimaryActivity();
 
-    SampleProvider getSampleProvider();
-
-    InstallHandler findInstallHandler(Uri uri, Context context);
-
-    boolean allowFetchActivityData(GBDevice device);
-
+    /**
+     * Returns true if activity data fetching is supported by the device
+     * (with this coordinator).
+     * @return
+     */
     boolean supportsActivityDataFetching();
 
+    /**
+     * Returns true if activity data fetching is supported AND possible at this
+     * very moment. This will consider the device state (being connected/disconnected/busy...)
+     * etc.
+     * @param device
+     * @return
+     */
+    boolean allowFetchActivityData(GBDevice device);
+
+    /**
+     * Returns the sample provider for the device being supported.
+     * @return
+     */
+    SampleProvider getSampleProvider();
+
+    /**
+     * Finds an install handler for the given uri that can install the given
+     * uri on the device being managed.
+     * @param uri
+     * @param context
+     * @return the install handler or null if that uri cannot be installed on the device
+     */
+    InstallHandler findInstallHandler(Uri uri, Context context);
+
+    /**
+     * Returns true if this device/coordinator supports taking screenshots.
+     * @return
+     */
     boolean supportsScreenshots();
 }

app/src/main/java/nodomain/freeyourgadget/gadgetbridge/impl/GBDeviceCandidate.java

@@ -9,6 +9,9 @@ import nodomain.freeyourgadget.gadgetbridge.R;
 import nodomain.freeyourgadget.gadgetbridge.model.DeviceType;
 
 /**
+ * A device candidate is a Bluetooth device that is not yet managed by
+ * Gadgetbridge. Only if a DeviceCoordinator steps up and confirms to
+ * support this candidate, will the candidate be promoted to a GBDevice.
  */
 public class GBDeviceCandidate implements Parcelable {
     private BluetoothDevice device;

app/src/main/java/nodomain/freeyourgadget/gadgetbridge/model/DeviceType.java

@@ -1,7 +1,11 @@
 package nodomain.freeyourgadget.gadgetbridge.model;
 
+/**
+ * For every supported device, a device type constant must exist.
+ */
 public enum DeviceType {
     UNKNOWN,
     PEBBLE,
-    TEST, MIBAND
+    TEST,
+    MIBAND
 }