From ec9e999be1613204e7940062ae953717bf93c327 Mon Sep 17 00:00:00 2001
From: cpfeiffer <cpfeiffer@users.noreply.github.com>
Date: Sat, 27 Aug 2016 16:44:47 +0200
Subject: [PATCH] Lots of documentation

---
 TODO.md                                       |  4 +-
 .../gadgetbridge/devices/SampleProvider.java  | 50 +++++++++++++++++++
 2 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/TODO.md b/TODO.md
index 0921e3a96..f309b267b 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,8 +1,8 @@
 TODO before 0.12.0 release:
 
 * ~~Support importing Pebble Health data from old database~~ DONE, needs check.
-* Fix user attribute table being spammed
-* Add onboarding activity on first startup (to merge old data)
+* ~~Add onboarding activity on first startup (to merge old data)~~ DONE, needs check.
+* Rename ActivitySample to Sample or something similar, and also related methods.
 
 Non blocking issues:
 
diff --git a/app/src/main/java/nodomain/freeyourgadget/gadgetbridge/devices/SampleProvider.java b/app/src/main/java/nodomain/freeyourgadget/gadgetbridge/devices/SampleProvider.java
index ba931695b..4c67d289e 100644
--- a/app/src/main/java/nodomain/freeyourgadget/gadgetbridge/devices/SampleProvider.java
+++ b/app/src/main/java/nodomain/freeyourgadget/gadgetbridge/devices/SampleProvider.java
@@ -1,9 +1,16 @@
 package nodomain.freeyourgadget.gadgetbridge.devices;
 
+import android.support.annotation.NonNull;
+
 import java.util.List;
 
 import nodomain.freeyourgadget.gadgetbridge.entities.AbstractActivitySample;
 
+/**
+ * Interface to retrieve samples from the database, and also create and add samples to the database.
+ * There are multiple device specific implementations, this interface defines the generic access.
+ * @param <T> the device/provider specific sample type (must extend AbstractActivitySample)
+ */
 public interface SampleProvider<T extends AbstractActivitySample> {
     // TODO: these constants can all be removed
     int PROVIDER_MIBAND = 0;
@@ -14,6 +21,12 @@ public interface SampleProvider<T extends AbstractActivitySample> {
 
     int PROVIDER_UNKNOWN = 100;
     // TODO: can also be removed
+
+    /**
+     * Returns the "id" of this sample provider, as used in Gadgetbridge versions < 0.12.0.
+     * Only used for importing old samples.
+     * @deprecated
+     */
     int getID();
 
     int normalizeType(int rawType);
@@ -22,15 +35,52 @@ public interface SampleProvider<T extends AbstractActivitySample> {
 
     float normalizeIntensity(int rawIntensity);
 
+    /**
+     * Returns the list of all samples, of any type, within the given time span.
+     * @param timestamp_from the start timestamp
+     * @param timestamp_to the end timestamp
+     * @return the list of samples of any type
+     */
+    @NonNull
     List<T> getAllActivitySamples(int timestamp_from, int timestamp_to);
 
+    /**
+     * Returns the list of all samples that represent user "activity", within
+     * the given time span. This excludes samples of type sleep, for example.
+     * @param timestamp_from the start timestamp
+     * @param timestamp_to the end timestamp
+     * @return the list of samples of type user activity, e.g. non-sleep
+     */
+    @NonNull
     List<T> getActivitySamples(int timestamp_from, int timestamp_to);
 
+    /**
+     * Returns the list of all samples that represent "sleeping", within the
+     * given time span.
+     * @param timestamp_from the start timestamp
+     * @param timestamp_to the end timestamp
+     * @return the list of samples of type sleep
+     */
+    @NonNull
     List<T> getSleepSamples(int timestamp_from, int timestamp_to);
 
+    /**
+     * Adds the given sample to the database. An existing sample with the same
+     * timestamp will be overwritten.
+     * @param activitySample the sample to add
+     */
     void addGBActivitySample(T activitySample);
 
+    /**
+     * Adds the given samples to the database. Existing samples with the same
+     * timestamp will be overwritten.
+     * @param activitySamples the samples to add
+     */
     void addGBActivitySamples(T[] activitySamples);
 
+    /**
+     * Factory method to creates an empty sample of the correct type for this sample provider
+     * @return the newly created "empty" sample
+     */
     T createActivitySample();
 }