From 9f2dabf2559824e4916fe31089b38ab4300b6db2 Mon Sep 17 00:00:00 2001
From: Fabian Kozynski <kozynski@google.com>
Date: Tue, 25 Feb 2020 14:17:35 -0500
Subject: [PATCH] Add docs to Controls API

Test: build
Bug: 150154816
Change-Id: Ie1f77620f8302032845ae1f66459b2990513bb86
---
 .../android/service/controls/Control.java     | 75 ++++++++++++++++++-
 .../android/service/controls/DeviceTypes.java |  3 +
 .../controls/actions/BooleanAction.java       | 14 ++--
 .../controls/actions/CommandAction.java       | 20 +++++
 .../controls/actions/ControlAction.java       | 18 ++++-
 .../service/controls/actions/ModeAction.java  | 24 ++++++
 .../controls/templates/ControlTemplate.java   | 15 ++++
 .../controls/templates/RangeTemplate.java     |  3 +-
 .../controls/templates/StatelessTemplate.java | 16 +++-
 .../templates/TemperatureControlTemplate.java | 24 ++++++
 .../templates/ToggleRangeTemplate.java        | 24 ++++++
 11 files changed, 225 insertions(+), 11 deletions(-)

diff --git a/core/java/android/service/controls/Control.java b/core/java/android/service/controls/Control.java
index 2d1d0ede62ca5..0cffe7180923a 100644
--- a/core/java/android/service/controls/Control.java
+++ b/core/java/android/service/controls/Control.java
@@ -394,6 +394,11 @@ public final class Control implements Parcelable {
             return this;
         }
 
+        /**
+         * @param deviceType the device type for the {@link Control}. Setting an invalid value not
+         *                   in {@link DeviceTypes} will set it to {@link DeviceTypes#TYPE_UNKNOWN}.
+         * @return {@code this}
+         */
         @NonNull
         public StatelessBuilder setDeviceType(@DeviceTypes.DeviceType int deviceType) {
             if (!DeviceTypes.validDeviceType(deviceType)) {
@@ -416,6 +421,10 @@ public final class Control implements Parcelable {
             return this;
         }
 
+        /**
+         * @param subtitle the user facing subtitle for the {@link Control}
+         * @return {@code this}
+         */
         @NonNull
         public StatelessBuilder setSubtitle(@NonNull CharSequence subtitle) {
             Preconditions.checkNotNull(subtitle);
@@ -423,12 +432,22 @@ public final class Control implements Parcelable {
             return this;
         }
 
+        /**
+         * @param structure the user facing name of the structure for the {@link Control}.
+         *                  {@code null} indicates that it's not associated with any structure.
+         * @return {@code this}
+         */
         @NonNull
         public StatelessBuilder setStructure(@Nullable CharSequence structure) {
             mStructure = structure;
             return this;
         }
 
+        /**
+         * @param zone the user facing name of the zone for the {@link Control}. {@code null}
+         *             indicates that it's not associated with any zone.
+         * @return {@code this}
+         */
         @NonNull
         public StatelessBuilder setZone(@Nullable CharSequence zone) {
             mZone = zone;
@@ -446,12 +465,20 @@ public final class Control implements Parcelable {
             return this;
         }
 
+        /**
+         * @param customIcon an {@link Icon} to override the one determined by the device type.
+         * @return {@code this}
+         */
         @NonNull
         public StatelessBuilder setCustomIcon(@Nullable Icon customIcon) {
             mCustomIcon = customIcon;
             return this;
         }
 
+        /**
+         * @param customColor a list of colors to override the ones determined by the device type.
+         * @return {@code this}
+         */
         @NonNull
         public StatelessBuilder setCustomColor(@Nullable ColorStateList customColor) {
             mCustomColor = customColor;
@@ -459,7 +486,7 @@ public final class Control implements Parcelable {
         }
 
         /**
-         * Build a {@link Control}
+         * Build a stateless {@link Control}
          * @return a valid {@link Control}
          */
         @NonNull
@@ -482,7 +509,7 @@ public final class Control implements Parcelable {
     /**
      * Builder class for {@link Control}.
      *
-     * This class facilitates the creation of {@link Control}.
+     * This class facilitates the creation of {@link Control} with an associated state.
      * It provides the following defaults for non-optional parameters:
      * <ul>
      *     <li> Device type: {@link DeviceTypes#TYPE_UNKNOWN}
@@ -551,6 +578,11 @@ public final class Control implements Parcelable {
             return this;
         }
 
+        /**
+         * @param deviceType the device type for the {@link Control}. Setting an invalid value not
+         *                   in {@link DeviceTypes} will set it to {@link DeviceTypes#TYPE_UNKNOWN}.
+         * @return {@code this}
+         */
         @NonNull
         public StatefulBuilder setDeviceType(@DeviceTypes.DeviceType int deviceType) {
             if (!DeviceTypes.validDeviceType(deviceType)) {
@@ -573,6 +605,10 @@ public final class Control implements Parcelable {
             return this;
         }
 
+        /**
+         * @param subtitle the user facing subtitle for the {@link Control}
+         * @return {@code this}
+         */
         @NonNull
         public StatefulBuilder setSubtitle(@NonNull CharSequence subtitle) {
             Preconditions.checkNotNull(subtitle);
@@ -580,12 +616,22 @@ public final class Control implements Parcelable {
             return this;
         }
 
+        /**
+         * @param structure the user facing name of the structure for the {@link Control}.
+         *                  {@code null} indicates that it's not associated with any structure.
+         * @return {@code this}
+         */
         @NonNull
         public StatefulBuilder setStructure(@Nullable CharSequence structure) {
             mStructure = structure;
             return this;
         }
 
+        /**
+         * @param zone the user facing name of the zone for the {@link Control}. {@code null}
+         *             indicates that it's not associated with any zone.
+         * @return {@code this}
+         */
         @NonNull
         public StatefulBuilder setZone(@Nullable CharSequence zone) {
             mZone = zone;
@@ -603,18 +649,31 @@ public final class Control implements Parcelable {
             return this;
         }
 
+        /**
+         * @param customIcon an {@link Icon} to override the one determined by the device type.
+         * @return {@code this}
+         */
         @NonNull
         public StatefulBuilder setCustomIcon(@Nullable Icon customIcon) {
             mCustomIcon = customIcon;
             return this;
         }
 
+        /**
+         * @param customColor a list of colors to override the ones determined by the device type.
+         * @return {@code this}
+         */
         @NonNull
         public StatefulBuilder setCustomColor(@Nullable ColorStateList customColor) {
             mCustomColor = customColor;
             return this;
         }
 
+        /**
+         * @param status the status of the {@link Control}. Setting an invalid value not in
+         *               {@link Control} will set it to {@link Control#STATUS_UNKNOWN}.
+         * @return {@code this}
+         */
         @NonNull
         public StatefulBuilder setStatus(@Status int status) {
             if (status < 0 || status >= NUM_STATUS) {
@@ -626,6 +685,10 @@ public final class Control implements Parcelable {
             return this;
         }
 
+        /**
+         * @param controlTemplate a template for the {@link Control}
+         * @return {@code this}
+         */
         @NonNull
         public StatefulBuilder setControlTemplate(@NonNull ControlTemplate controlTemplate) {
             Preconditions.checkNotNull(controlTemplate);
@@ -633,6 +696,10 @@ public final class Control implements Parcelable {
             return this;
         }
 
+        /**
+         * @param statusText a user facing text representing the status of the {@link Control}.
+         * @return {@code this}
+         */
         @NonNull
         public StatefulBuilder setStatusText(@NonNull CharSequence statusText) {
             Preconditions.checkNotNull(statusText);
@@ -640,6 +707,10 @@ public final class Control implements Parcelable {
             return this;
         }
 
+        /**
+         * Build a stateless {@link Control}
+         * @return a valid {@link Control}
+         */
         @NonNull
         public Control build() {
             return new Control(mControlId,
diff --git a/core/java/android/service/controls/DeviceTypes.java b/core/java/android/service/controls/DeviceTypes.java
index 8dbb9cf8f9f7f..6594d2cf4ba23 100644
--- a/core/java/android/service/controls/DeviceTypes.java
+++ b/core/java/android/service/controls/DeviceTypes.java
@@ -21,6 +21,9 @@ import android.annotation.IntDef;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/**
+ * Device types for {@link Control}.
+ */
 public class DeviceTypes {
 
     // Update this when adding new concrete types. Does not count TYPE_UNKNOWN
diff --git a/core/java/android/service/controls/actions/BooleanAction.java b/core/java/android/service/controls/actions/BooleanAction.java
index 02593353bfc89..b794eadf0f909 100644
--- a/core/java/android/service/controls/actions/BooleanAction.java
+++ b/core/java/android/service/controls/actions/BooleanAction.java
@@ -19,10 +19,15 @@ package android.service.controls.actions;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.os.Bundle;
+import android.service.controls.Control;
+import android.service.controls.templates.ToggleRangeTemplate;
 import android.service.controls.templates.ToggleTemplate;
 
 /**
- * Action sent by a {@link ToggleTemplate}
+ * Action sent by user toggling a {@link Control} between checked/unchecked.
+ *
+ * This action is available when the {@link Control} was constructed with either a
+ * {@link ToggleTemplate} or a {@link ToggleRangeTemplate}.
  */
 public final class BooleanAction extends ControlAction {
 
@@ -40,8 +45,8 @@ public final class BooleanAction extends ControlAction {
     }
 
     /**
-     * @param templateId the identifier of the {@link ToggleTemplate} that originated this action.
-     * @param newState new value for the state displayed by the {@link ToggleTemplate}.
+     * @param templateId the identifier of the template that originated this action.
+     * @param newState new value for the state displayed by the template.
      * @param challengeValue a value sent by the user along with the action to authenticate. {@code}
      *                       null is sent when no authentication is needed or has not been
      *                       requested.
@@ -64,8 +69,7 @@ public final class BooleanAction extends ControlAction {
     /**
      * The new state set for the button in the corresponding {@link ToggleTemplate}.
      *
-     * @return {@code true} if the button was toggled from an {@code off} state to an {@code on}
-     *         state.
+     * @return {@code true} if the button was toggled from unchecked to checked.
      */
     public boolean getNewState() {
         return mNewState;
diff --git a/core/java/android/service/controls/actions/CommandAction.java b/core/java/android/service/controls/actions/CommandAction.java
index 84d60805c3e91..a560fa4268aab 100644
--- a/core/java/android/service/controls/actions/CommandAction.java
+++ b/core/java/android/service/controls/actions/CommandAction.java
@@ -19,15 +19,32 @@ package android.service.controls.actions;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.os.Bundle;
+import android.service.controls.Control;
+import android.service.controls.templates.StatelessTemplate;
 
+/**
+ * A simple {@link ControlAction} indicating that the user has interacted with a {@link Control}
+ * created using a {@link StatelessTemplate}.
+ */
 public final class CommandAction extends ControlAction {
 
     private static final @ActionType int TYPE = TYPE_COMMAND;
 
+    /**
+     * @param templateId the identifier of the {@link StatelessTemplate} that originated this
+     *                   action.
+     * @param challengeValue a value sent by the user along with the action to authenticate. {@code}
+     *                       null is sent when no authentication is needed or has not been
+     *                       requested.
+     */
     public CommandAction(@NonNull String templateId, @Nullable String challengeValue) {
         super(templateId, challengeValue);
     }
 
+    /**
+     * @param templateId the identifier of the {@link StatelessTemplate} that originated this
+     *                   action.
+     */
     public CommandAction(@NonNull String templateId) {
         this(templateId, null);
     }
@@ -40,6 +57,9 @@ public final class CommandAction extends ControlAction {
         super(b);
     }
 
+    /**
+     * @return {@link ControlAction#TYPE_COMMAND}
+     */
     @Override
     public int getActionType() {
         return TYPE;
diff --git a/core/java/android/service/controls/actions/ControlAction.java b/core/java/android/service/controls/actions/ControlAction.java
index 4141da805b5a2..45e63d772d73f 100644
--- a/core/java/android/service/controls/actions/ControlAction.java
+++ b/core/java/android/service/controls/actions/ControlAction.java
@@ -21,6 +21,7 @@ import android.annotation.IntDef;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.os.Bundle;
+import android.service.controls.Control;
 import android.service.controls.IControlsActionCallback;
 import android.service.controls.templates.ControlTemplate;
 import android.util.Log;
@@ -31,7 +32,7 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * An abstract action that is executed from a {@link ControlTemplate}.
+ * An abstract action indicating a user interaction with a {@link Control}.
  *
  * The action may have a value to authenticate the input, when the provider has requested it to
  * complete the action.
@@ -58,6 +59,9 @@ public abstract class ControlAction {
     })
     public @interface ActionType {};
 
+    /**
+     * Object returned when there is an unparcelling error.
+     */
     public static final @NonNull ControlAction ERROR_ACTION = new ControlAction() {
         @Override
         public int getActionType() {
@@ -65,6 +69,9 @@ public abstract class ControlAction {
         }
     };
 
+    /**
+     * The identifier of {@link #ERROR_ACTION}
+     */
     public static final @ActionType int TYPE_ERROR = -1;
 
     /**
@@ -77,10 +84,19 @@ public abstract class ControlAction {
      */
     public static final @ActionType int TYPE_FLOAT = 2;
 
+    /**
+     * The identifier of {@link MultiFloatAction}.
+     */
     public static final @ActionType int TYPE_MULTI_FLOAT = 3;
 
+    /**
+     * The identifier of {@link ModeAction}.
+     */
     public static final @ActionType int TYPE_MODE = 4;
 
+    /**
+     * The identifier of {@link CommandAction}.
+     */
     public static final @ActionType int TYPE_COMMAND = 5;
 
 
diff --git a/core/java/android/service/controls/actions/ModeAction.java b/core/java/android/service/controls/actions/ModeAction.java
index ca40974d929bc..c0e24adb18f35 100644
--- a/core/java/android/service/controls/actions/ModeAction.java
+++ b/core/java/android/service/controls/actions/ModeAction.java
@@ -19,7 +19,15 @@ package android.service.controls.actions;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.os.Bundle;
+import android.service.controls.Control;
+import android.service.controls.templates.TemperatureControlTemplate;
 
+/**
+ * Action sent by the user to indicate a change of mode.
+ *
+ * This action is available when the {@link Control} was created with a
+ * {@link TemperatureControlTemplate}.
+ */
 public final class ModeAction extends ControlAction {
 
     private static final @ActionType int TYPE = TYPE_MODE;
@@ -27,16 +35,32 @@ public final class ModeAction extends ControlAction {
 
     private final int mNewMode;
 
+    /**
+     * @return {@link ControlAction#TYPE_MODE}.
+     */
     @Override
     public int getActionType() {
         return TYPE;
     }
 
+    /**
+     * @param templateId the identifier of the {@link TemperatureControlTemplate} that originated
+     *                   this action.
+     * @param newMode new value for the mode.
+     * @param challengeValue a value sent by the user along with the action to authenticate. {@code}
+     *                       null is sent when no authentication is needed or has not been
+     *                       requested.
+     */
     public ModeAction(@NonNull String templateId, int newMode, @Nullable String challengeValue) {
         super(templateId, challengeValue);
         mNewMode = newMode;
     }
 
+    /**
+     * @param templateId the identifier of the {@link TemperatureControlTemplate} that originated
+     *                   this action.
+     * @param newMode new value for the mode.
+     */
     public ModeAction(@NonNull String templateId, int newMode) {
         this(templateId, newMode, null);
     }
diff --git a/core/java/android/service/controls/templates/ControlTemplate.java b/core/java/android/service/controls/templates/ControlTemplate.java
index a5156e36f2ced..30efd80db1066 100644
--- a/core/java/android/service/controls/templates/ControlTemplate.java
+++ b/core/java/android/service/controls/templates/ControlTemplate.java
@@ -57,6 +57,9 @@ public abstract class ControlTemplate {
         }
     };
 
+    /**
+     * Object returned when there is an unparcelling error.
+     */
     public static final @NonNull ControlTemplate ERROR_TEMPLATE = new ControlTemplate("") {
         @Override
         public int getTemplateType() {
@@ -80,6 +83,9 @@ public abstract class ControlTemplate {
     })
     public @interface TemplateType {}
 
+    /**
+     * Type identifier of {@link #ERROR_TEMPLATE}.
+     */
     public static final @TemplateType int TYPE_ERROR = -1;
 
     /**
@@ -102,10 +108,19 @@ public abstract class ControlTemplate {
      */
     public static final @TemplateType int TYPE_THUMBNAIL = 3;
 
+    /**
+     * Type identifier of {@link ToggleRangeTemplate}.
+     */
     public static final @TemplateType int TYPE_TOGGLE_RANGE = 6;
 
+    /**
+     * Type identifier of {@link TemperatureControlTemplate}.
+     */
     public static final @TemplateType int TYPE_TEMPERATURE = 7;
 
+    /**
+     * Type identifier of {@link StatelessTemplate}.
+     */
     public static final @TemplateType int TYPE_STATELESS = 8;
 
     private @NonNull final String mTemplateId;
diff --git a/core/java/android/service/controls/templates/RangeTemplate.java b/core/java/android/service/controls/templates/RangeTemplate.java
index fe0d16707c9dd..0d977d30f7c1c 100644
--- a/core/java/android/service/controls/templates/RangeTemplate.java
+++ b/core/java/android/service/controls/templates/RangeTemplate.java
@@ -19,7 +19,6 @@ package android.service.controls.templates;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.os.Bundle;
-import android.os.Parcel;
 import android.service.controls.Control;
 import android.service.controls.actions.FloatAction;
 
@@ -85,7 +84,7 @@ public final class RangeTemplate extends ControlTemplate {
     }
 
     /**
-     * Construct a new {@link RangeTemplate} from a {@link Parcel}.
+     * Construct a new {@link RangeTemplate} from a {@link Bundle}.
      *
      * @throws IllegalArgumentException if the parameters passed do not make a valid range
      * @see RangeTemplate#RangeTemplate(String, float, float, float, float, CharSequence)
diff --git a/core/java/android/service/controls/templates/StatelessTemplate.java b/core/java/android/service/controls/templates/StatelessTemplate.java
index 3f98beac9cf89..c052412f0e4c5 100644
--- a/core/java/android/service/controls/templates/StatelessTemplate.java
+++ b/core/java/android/service/controls/templates/StatelessTemplate.java
@@ -18,22 +18,36 @@ package android.service.controls.templates;
 
 import android.annotation.NonNull;
 import android.os.Bundle;
+import android.service.controls.Control;
+import android.service.controls.actions.CommandAction;
 
+/**
+ * A template for a {@link Control} which has no state.
+ *
+ * @see CommandAction
+ */
 public final class StatelessTemplate extends ControlTemplate {
 
+    /**
+     * @return {@link ControlTemplate#TYPE_STATELESS}
+     */
     @Override
     public int getTemplateType() {
         return TYPE_STATELESS;
     }
 
     /**
-     * @param b
+     * Construct a new {@link StatelessTemplate} from a {@link Bundle}
      * @hide
      */
     StatelessTemplate(@NonNull Bundle b) {
         super(b);
     }
 
+    /**
+     * Construct a new {@link StatelessTemplate}
+     * @param templateId the identifier for this template
+     */
     public StatelessTemplate(@NonNull String templateId) {
         super(templateId);
     }
diff --git a/core/java/android/service/controls/templates/TemperatureControlTemplate.java b/core/java/android/service/controls/templates/TemperatureControlTemplate.java
index 9d8dca6278c5a..0818c7e4fb827 100644
--- a/core/java/android/service/controls/templates/TemperatureControlTemplate.java
+++ b/core/java/android/service/controls/templates/TemperatureControlTemplate.java
@@ -19,6 +19,7 @@ package android.service.controls.templates;
 import android.annotation.IntDef;
 import android.annotation.NonNull;
 import android.os.Bundle;
+import android.service.controls.Control;
 import android.util.Log;
 
 import com.android.internal.util.Preconditions;
@@ -26,6 +27,13 @@ import com.android.internal.util.Preconditions;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/**
+ * A template for a temperature related {@link Control} that supports multiple modes.
+ *
+ * Both the current mode and the active mode for the control can be specified. The combination of
+ * the {@link Control#getDeviceType} and the current and active mode will determine colors and
+ * transitions for the UI element.
+ */
 public final class TemperatureControlTemplate extends ControlTemplate {
 
     private static final String TAG = "ThermostatTemplate";
@@ -51,6 +59,7 @@ public final class TemperatureControlTemplate extends ControlTemplate {
     public @interface Mode {}
 
     private static final int NUM_MODES = 6;
+
     public static final @Mode int MODE_UNKNOWN = 0;
 
     public static final @Mode int MODE_OFF = 1;
@@ -102,6 +111,18 @@ public final class TemperatureControlTemplate extends ControlTemplate {
     private final @Mode int mCurrentActiveMode;
     private final @ModeFlag int mModes;
 
+    /**
+     * Construct a new {@link TemperatureControlTemplate}.
+     *
+     * The current and active mode have to be among the ones supported by the flags.
+     *
+     * @param templateId the identifier for this template object
+     * @param controlTemplate a template to use for interaction with the user
+     * @param currentMode the current mode for the {@link Control}
+     * @param currentActiveMode the current active mode for the {@link Control}
+     * @param modesFlag a flag representing the available modes for the {@link Control}
+     * @throws IllegalArgumentException if the parameters passed do not make a valid template.
+     */
     public TemperatureControlTemplate(@NonNull String templateId,
             @NonNull ControlTemplate controlTemplate,
             @Mode int currentMode,
@@ -179,6 +200,9 @@ public final class TemperatureControlTemplate extends ControlTemplate {
         return mModes;
     }
 
+    /**
+     * @return {@link ControlTemplate#TYPE_TEMPERATURE}
+     */
     @Override
     public int getTemplateType() {
         return TYPE;
diff --git a/core/java/android/service/controls/templates/ToggleRangeTemplate.java b/core/java/android/service/controls/templates/ToggleRangeTemplate.java
index af43b94699d21..cd6a2fc456125 100644
--- a/core/java/android/service/controls/templates/ToggleRangeTemplate.java
+++ b/core/java/android/service/controls/templates/ToggleRangeTemplate.java
@@ -18,9 +18,16 @@ package android.service.controls.templates;
 
 import android.annotation.NonNull;
 import android.os.Bundle;
+import android.service.controls.Control;
 
 import com.android.internal.util.Preconditions;
 
+/**
+ * A template for a {@link Control} supporting toggling and a range.
+ *
+ * @see ToggleTemplate
+ * @see RangeTemplate
+ */
 public final class ToggleRangeTemplate extends ControlTemplate {
 
     private static final @TemplateType int TYPE = TYPE_TOGGLE_RANGE;
@@ -40,6 +47,12 @@ public final class ToggleRangeTemplate extends ControlTemplate {
         mRangeTemplate = new RangeTemplate(b.getBundle(KEY_RANGE));
     }
 
+    /**
+     * Constructs a new {@link ToggleRangeTemplate}.
+     * @param templateId the identifier for this template.
+     * @param button a {@link ControlButton} to use for the toggle interface
+     * @param range a {@link RangeTemplate} to use for the range interface
+     */
     public ToggleRangeTemplate(@NonNull String templateId,
             @NonNull ControlButton button,
             @NonNull RangeTemplate range) {
@@ -50,6 +63,14 @@ public final class ToggleRangeTemplate extends ControlTemplate {
         mRangeTemplate = range;
     }
 
+    /**
+     * Constructs a new {@link ToggleRangeTemplate}.
+     * @param templateId the identifier for this template.
+     * @param checked true if the toggle should be rendered as active.
+     * @param actionDescription action description for the button.
+     * @param range  {@link RangeTemplate} to use for the range interface
+     * @see ControlButton
+     */
     public ToggleRangeTemplate(@NonNull String templateId,
             boolean checked,
             @NonNull CharSequence actionDescription,
@@ -86,6 +107,9 @@ public final class ToggleRangeTemplate extends ControlTemplate {
         return mControlButton.getActionDescription();
     }
 
+    /**
+     * @return {@link ControlTemplate#TYPE_TOGGLE_RANGE}
+     */
     @Override
     public int getTemplateType() {
         return TYPE;