Clarify comments for validity period and resources name.
Bug: 186543685
Bug: 186542736
Test: Pure comment refactoring.
Relnote: n/a
Change-Id: I0aba0b301ae41f6eb4b6159dfbdb2faab00f7329
diff --git a/wear/tiles/tiles-proto/src/main/proto/layout.proto b/wear/tiles/tiles-proto/src/main/proto/layout.proto
index ea3d8d8..008344f 100644
--- a/wear/tiles/tiles-proto/src/main/proto/layout.proto
+++ b/wear/tiles/tiles-proto/src/main/proto/layout.proto
@@ -312,6 +312,7 @@
// An extensible ContentScaleMode property.
message ContentScaleModeProp {
+ // The value
ContentScaleMode value = 1;
}
diff --git a/wear/tiles/tiles-proto/src/main/proto/requests.proto b/wear/tiles/tiles-proto/src/main/proto/requests.proto
index 17e9522..9fcdfa0 100644
--- a/wear/tiles/tiles-proto/src/main/proto/requests.proto
+++ b/wear/tiles/tiles-proto/src/main/proto/requests.proto
@@ -22,7 +22,8 @@
// Parameters passed to a Tile provider when the renderer is requesting a
// specific resource version.
message ResourcesRequest {
- // The version of the resources being fetched
+ // The version of the resources being fetched. This is the same as the
+ // requested resource version, passed in Tile.
string version = 1;
// Requested resource IDs. If not specified, all resources for the given
diff --git a/wear/tiles/tiles-proto/src/main/proto/resources.proto b/wear/tiles/tiles-proto/src/main/proto/resources.proto
index 652e130..eb4d8af 100644
--- a/wear/tiles/tiles-proto/src/main/proto/resources.proto
+++ b/wear/tiles/tiles-proto/src/main/proto/resources.proto
@@ -64,7 +64,8 @@
// to separately fetch the resources.
//
// This value must match the version of the resources required by the tile
- // for the tile to render successfully.
+ // for the tile to render successfully, and must match the resource version
+ // specified in ResourcesRequest which triggered this request.
string version = 1;
// A map of resource_ids to images, which can be used by layouts.
diff --git a/wear/tiles/tiles-proto/src/main/proto/tile.proto b/wear/tiles/tiles-proto/src/main/proto/tile.proto
index 1bbded9..fb41af4 100644
--- a/wear/tiles/tiles-proto/src/main/proto/tile.proto
+++ b/wear/tiles/tiles-proto/src/main/proto/tile.proto
@@ -12,7 +12,10 @@
// A holder for a tile. This specifies the resources to use for this delivery
// of the tile, and the timeline for the tile.
message Tile {
- // The resource version required for these tiles.
+ // The resource version required for these tiles. This can be any developer-defined
+ // string; it is only used to cache resources, and is passed in
+ // ResourcesRequest if the system does not have a copy of the specified
+ // resource version.
string resources_version = 1;
// The tiles to show in the carousel, along with their validity periods.
@@ -26,5 +29,12 @@
// your tile at some point in the future after this interval has lapsed. A
// value of 0 here signifies that auto-refreshes should not be used (i.e. you
// will manually request updates via TileProviderService#getRequester).
+ //
+ // This mechanism should not be used to update your tile more frequently than
+ // once a minute, and the system may throttle your updates if you request
+ // updates faster than this interval. This interval is also inexact; the
+ // system will generally update your tile if it is on-screen, or about to be
+ // on-screen, although this is not guaranteed due to system-level
+ // optimizations.
uint64 freshness_interval_millis = 4;
}
diff --git a/wear/tiles/tiles/src/main/java/androidx/wear/tiles/builders/ResourceBuilders.java b/wear/tiles/tiles/src/main/java/androidx/wear/tiles/builders/ResourceBuilders.java
index fde80e0..e2d8230 100644
--- a/wear/tiles/tiles/src/main/java/androidx/wear/tiles/builders/ResourceBuilders.java
+++ b/wear/tiles/tiles/src/main/java/androidx/wear/tiles/builders/ResourceBuilders.java
@@ -324,7 +324,8 @@
* the resources.
*
* <p>This value must match the version of the resources required by the tile for the
- * tile to render successfully.
+ * tile to render successfully, and must match the resource version specified in
+ * ResourcesRequest which triggered this request.
*/
@SuppressLint("MissingGetterMatchingBuilder")
@NonNull
diff --git a/wear/tiles/tiles/src/main/java/androidx/wear/tiles/builders/TileBuilders.java b/wear/tiles/tiles/src/main/java/androidx/wear/tiles/builders/TileBuilders.java
index ff5b034..847aacd 100644
--- a/wear/tiles/tiles/src/main/java/androidx/wear/tiles/builders/TileBuilders.java
+++ b/wear/tiles/tiles/src/main/java/androidx/wear/tiles/builders/TileBuilders.java
@@ -66,8 +66,12 @@
Builder() {}
- /** Sets the resource version required for these tiles. */
@SuppressLint("MissingGetterMatchingBuilder")
+ /**
+ * Sets the resource version required for these tiles. This can be any developer-defined
+ * string; it is only used to cache resources, and is passed in ResourcesRequest if the
+ * system does not have a copy of the specified resource version.
+ */
@NonNull
public Builder setResourcesVersion(@NonNull String resourcesVersion) {
mImpl.setResourcesVersion(resourcesVersion);
@@ -96,6 +100,12 @@
* point in the future after this interval has lapsed. A value of 0 here signifies that
* auto-refreshes should not be used (i.e. you will manually request updates via
* TileProviderService#getRequester).
+ *
+ * <p>This mechanism should not be used to update your tile more frequently than once a
+ * minute, and the system may throttle your updates if you request updates faster than
+ * this interval. This interval is also inexact; the system will generally update your
+ * tile if it is on-screen, or about to be on-screen, although this is not guaranteed
+ * due to system-level optimizations.
*/
@SuppressLint("MissingGetterMatchingBuilder")
@NonNull