Revise javadoc for Rating classes

PiperOrigin-RevId: 371625281

library/common/src/main/java/com/google/android/exoplayer2/HeartRating.java

@@ -26,42 +26,40 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * A class for rating with a single degree of rating, "heart" vs "no heart". This can be used to
- * indicate the content referred to is a favorite (or not).
+ * A rating expressed as "heart" or "no heart". It can be used to indicate whether the content is a
+ * favorite.
  */
 public final class HeartRating extends Rating {
 
-  @RatingType private static final int TYPE = RATING_TYPE_HEART;
-
-  private final boolean isRated;
+  private final boolean rated;
 
-  /** Whether the rating has a heart rating or not. */
-  public final boolean hasHeart;
+  /** Whether the rating is "heart". */
+  public final boolean isHeart;
 
-  /** Creates a unrated HeartRating instance. */
+  /** Creates a unrated instance. */
   public HeartRating() {
-    isRated = false;
-    hasHeart = false;
+    rated = false;
+    isHeart = false;
   }
 
   /**
-   * Creates a HeartRating instance.
+   * Creates a rated instance.
    *
-   * @param hasHeart true for a "heart selected" rating, false for "heart unselected".
+   * @param isHeart {@code true} for "heart", {@code false} for "no heart".
    */
-  public HeartRating(boolean hasHeart) {
-    isRated = true;
-    this.hasHeart = hasHeart;
+  public HeartRating(boolean isHeart) {
+    rated = true;
+    this.isHeart = isHeart;
   }
 
   @Override
   public boolean isRated() {
-    return isRated;
+    return rated;
   }
 
   @Override
   public int hashCode() {
-    return Objects.hashCode(isRated, hasHeart);
+    return Objects.hashCode(rated, isHeart);
   }
 
   @Override
@@ -70,42 +68,40 @@ public final class HeartRating extends Rating {
       return false;
     }
     HeartRating other = (HeartRating) obj;
-    return hasHeart == other.hasHeart && isRated == other.isRated;
-  }
-
-  @Override
-  public String toString() {
-    return "HeartRating: " + (isRated ? "hasHeart=" + hasHeart : "unrated");
+    return isHeart == other.isHeart && rated == other.rated;
   }
 
   // Bundleable implementation.
+
+  @RatingType private static final int TYPE = RATING_TYPE_HEART;
+
   @Documented
   @Retention(RetentionPolicy.SOURCE)
-  @IntDef({FIELD_RATING_TYPE, FIELD_IS_RATED, FIELD_HAS_HEART})
+  @IntDef({FIELD_RATING_TYPE, FIELD_RATED, FIELD_IS_HEART})
   private @interface FieldNumber {}
 
-  private static final int FIELD_IS_RATED = 1;
-  private static final int FIELD_HAS_HEART = 2;
+  private static final int FIELD_RATED = 1;
+  private static final int FIELD_IS_HEART = 2;
 
   @Override
   public Bundle toBundle() {
     Bundle bundle = new Bundle();
     bundle.putInt(keyForField(FIELD_RATING_TYPE), TYPE);
-    bundle.putBoolean(keyForField(FIELD_IS_RATED), isRated);
-    bundle.putBoolean(keyForField(FIELD_HAS_HEART), hasHeart);
+    bundle.putBoolean(keyForField(FIELD_RATED), rated);
+    bundle.putBoolean(keyForField(FIELD_IS_HEART), isHeart);
     return bundle;
   }
 
+  /** Object that can restore a {@link HeartRating} from a {@link Bundle}. */
   public static final Creator<HeartRating> CREATOR = HeartRating::fromBundle;
 
   private static HeartRating fromBundle(Bundle bundle) {
     checkArgument(
         bundle.getInt(keyForField(FIELD_RATING_TYPE), /* defaultValue= */ RATING_TYPE_DEFAULT)
             == TYPE);
-    boolean isRated = bundle.getBoolean(keyForField(FIELD_IS_RATED), /* defaultValue= */ false);
+    boolean isRated = bundle.getBoolean(keyForField(FIELD_RATED), /* defaultValue= */ false);
     return isRated
-        ? new HeartRating(
-            bundle.getBoolean(keyForField(FIELD_HAS_HEART), /* defaultValue= */ false))
+        ? new HeartRating(bundle.getBoolean(keyForField(FIELD_IS_HEART), /* defaultValue= */ false))
         : new HeartRating();
   }
 

library/common/src/main/java/com/google/android/exoplayer2/PercentageRating.java

@@ -26,30 +26,27 @@ import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
-/** A class for rating expressed as a percentage. */
+/** A rating expressed as a percentage. */
 public final class PercentageRating extends Rating {
 
-  @RatingType private static final int TYPE = RATING_TYPE_PERCENTAGE;
-
   /**
-   * The percent value of this rating. Will be greater or equal to 0.0f, or {@link #RATING_UNSET} if
-   * it is unrated.
+   * The percent value of this rating. Will be within the range {@code [0f, 100f]}, or {@link
+   * #RATING_UNSET} if unrated.
    */
   public final float percent;
 
-  /** Creates a unrated PercentageRating instance. */
+  /** Creates a unrated instance. */
   public PercentageRating() {
     percent = RATING_UNSET;
   }
 
   /**
-   * Creates a PercentageRating instance with the given percentage. If {@code percent} is less than
-   * 0f or greater than 100f, it will throw IllegalArgumentException.
+   * Creates a rated instance with the given percentage.
    *
-   * @param percent the value of the rating
+   * @param percent The percentage value of the rating.
    */
   public PercentageRating(@FloatRange(from = 0, to = 100) float percent) {
-    checkArgument(percent >= 0.0f && percent <= 100.0f, "percent must be in the rage of [0, 100]");
+    checkArgument(percent >= 0.0f && percent <= 100.0f, "percent must be in the range of [0, 100]");
     this.percent = percent;
   }
 
@@ -71,12 +68,10 @@ public final class PercentageRating extends Rating {
     return percent == ((PercentageRating) obj).percent;
   }
 
-  @Override
-  public String toString() {
-    return "PercentageRating: " + (isRated() ? "percentage=" + percent : "unrated");
-  }
-
   // Bundleable implementation.
+
+  @RatingType private static final int TYPE = RATING_TYPE_PERCENTAGE;
+
   @Documented
   @Retention(RetentionPolicy.SOURCE)
   @IntDef({FIELD_RATING_TYPE, FIELD_PERCENT})
@@ -92,6 +87,7 @@ public final class PercentageRating extends Rating {
     return bundle;
   }
 
+  /** Object that can restore a {@link PercentageRating} from a {@link Bundle}. */
   public static final Creator<PercentageRating> CREATOR = PercentageRating::fromBundle;
 
   private static PercentageRating fromBundle(Bundle bundle) {

library/common/src/main/java/com/google/android/exoplayer2/Rating.java

@@ -21,11 +21,23 @@ import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
-/** An abstract class to encapsulate rating information used as content metadata. */
+/**
+ * A rating for media content. The style of a rating can be one of {@link HeartRating}, {@link
+ * PercentageRating}, {@link StarRating}, or {@link ThumbRating}.
+ */
 public abstract class Rating implements Bundleable {
 
+  /** A float value that denotes the rating is unset. */
   public static final float RATING_UNSET = -1.0f;
 
+  // Default package-private constructor to prevent extending Rating class outside this package.
+  /* package */ Rating() {}
+
+  /** Whether the rating exists or not. */
+  public abstract boolean isRated();
+
+  // Bundleable implementation.
+
   @Documented
   @Retention(RetentionPolicy.SOURCE)
   @IntDef({
@@ -35,28 +47,22 @@ public abstract class Rating implements Bundleable {
     RATING_TYPE_STAR,
     RATING_TYPE_THUMB
   })
-  protected @interface RatingType {}
-
-  protected static final int RATING_TYPE_DEFAULT = -1;
-  protected static final int RATING_TYPE_HEART = 0;
-  protected static final int RATING_TYPE_PERCENTAGE = 1;
-  protected static final int RATING_TYPE_STAR = 2;
-  protected static final int RATING_TYPE_THUMB = 3;
+  /* package */ @interface RatingType {}
 
-  // Default package-private constructor to prevent extending Rating class outside this package.
-  /* package */ Rating() {}
+  /* package */ static final int RATING_TYPE_DEFAULT = -1;
+  /* package */ static final int RATING_TYPE_HEART = 0;
+  /* package */ static final int RATING_TYPE_PERCENTAGE = 1;
+  /* package */ static final int RATING_TYPE_STAR = 2;
+  /* package */ static final int RATING_TYPE_THUMB = 3;
 
-  /** Whether rating exists or not. */
-  public abstract boolean isRated();
-
-  // Bundleable implementation.
   @Documented
   @Retention(RetentionPolicy.SOURCE)
   @IntDef({FIELD_RATING_TYPE})
   private @interface FieldNumber {}
 
-  protected static final int FIELD_RATING_TYPE = 0;
+  /* package */ static final int FIELD_RATING_TYPE = 0;
 
+  /** Object that can restore a {@link Rating} from a {@link Bundle}. */
   public static final Creator<Rating> CREATOR = Rating::fromBundle;
 
   private static Rating fromBundle(Bundle bundle) {

library/common/src/main/java/com/google/android/exoplayer2/StarRating.java

@@ -27,28 +27,24 @@ import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
-/** A class for rating expressed as the number of stars. */
+/** A rating expressed as a fractional number of stars. */
 public final class StarRating extends Rating {
 
-  @RatingType private static final int TYPE = RATING_TYPE_STAR;
-
-  private static final int MAX_STARS_DEFAULT = 5;
-
-  /** The maximum number of stars for this rating. Must be a positive number. */
+  /** The maximum number of stars. Must be a positive number. */
   @IntRange(from = 1)
   public final int maxStars;
 
   /**
-   * The value of stars for this rating. Will range from 0.0f to {@link #maxStars}, or {@link
-   * #RATING_UNSET} if it is unrated.
+   * The fractional number of stars of this rating. Will range from {@code 0f} to {@link #maxStars},
+   * or {@link #RATING_UNSET} if unrated.
    */
   public final float starRating;
 
   /**
-   * Creates a unrated StarRating instance with {@code maxStars}. If {@code maxStars} is not a
-   * positive integer, it will throw IllegalArgumentException.
+   * Creates a unrated instance with {@code maxStars}. If {@code maxStars} is not a positive
+   * integer, it will throw an {@link IllegalArgumentException}.
    *
-   * @param maxStars a range of this star rating from 0.0f to {@code maxStars}
+   * @param maxStars The maximum number of stars this rating can have.
    */
   public StarRating(@IntRange(from = 1) int maxStars) {
     checkArgument(maxStars > 0, "maxStars must be a positive integer");
@@ -57,13 +53,14 @@ public final class StarRating extends Rating {
   }
 
   /**
-   * Creates a StarRating instance with {@code maxStars} and the given integer or fractional number
-   * of stars. Non-integer values can for instance be used to represent an average rating value,
-   * which might not be an integer number of stars. If {@code maxStars} is not a positive integer or
-   * {@code starRating} has invalid value, it will throw IllegalArgumentException.
+   * Creates a rated instance with {@code maxStars} and the given fractional number of stars.
+   * Non-integer values may be used to represent an average rating value. If {@code maxStars} is not
+   * a positive integer or {@code starRating} is out of range, it will throw an {@link
+   * IllegalArgumentException}.
    *
-   * @param maxStars the maximum number of stars which this rating can have.
-   * @param starRating a number ranging from 0.0f to {@code maxStars}
+   * @param maxStars The maximum number of stars this rating can have.
+   * @param starRating A fractional number of stars of this rating from {@code 0f} to {@code
+   *     maxStars}.
    */
   public StarRating(@IntRange(from = 1) int maxStars, @FloatRange(from = 0.0) float starRating) {
     checkArgument(maxStars > 0, "maxStars must be a positive integer");
@@ -92,14 +89,11 @@ public final class StarRating extends Rating {
     return maxStars == other.maxStars && starRating == other.starRating;
   }
 
-  @Override
-  public String toString() {
-    return "StarRating: maxStars="
-        + maxStars
-        + (isRated() ? ", starRating=" + starRating : ", unrated");
-  }
-
   // Bundleable implementation.
+
+  @RatingType private static final int TYPE = RATING_TYPE_STAR;
+  private static final int MAX_STARS_DEFAULT = 5;
+
   @Documented
   @Retention(RetentionPolicy.SOURCE)
   @IntDef({FIELD_RATING_TYPE, FIELD_MAX_STARS, FIELD_STAR_RATING})
@@ -117,6 +111,7 @@ public final class StarRating extends Rating {
     return bundle;
   }
 
+  /** Object that can restore a {@link StarRating} from a {@link Bundle}. */
   public static final Creator<StarRating> CREATOR = StarRating::fromBundle;
 
   private static StarRating fromBundle(Bundle bundle) {

library/common/src/main/java/com/google/android/exoplayer2/ThumbRating.java

@@ -25,40 +25,38 @@ import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
-/** A class for rating with a single degree of rating, "thumb up" vs "thumb down". */
+/** A rating expressed as "thumbs up" or "thumbs down". */
 public final class ThumbRating extends Rating {
 
-  @RatingType private static final int TYPE = RATING_TYPE_THUMB;
-
-  private final boolean isRated;
+  private final boolean rated;
 
-  /** Whether the rating has a thumb up or thumb down rating. */
-  public final boolean thumbUp;
+  /** Whether the rating is "thumbs up". */
+  public final boolean isThumbsUp;
 
-  /** Creates a unrated ThumbRating instance. */
+  /** Creates a unrated instance. */
   public ThumbRating() {
-    isRated = false;
-    thumbUp = false;
+    rated = false;
+    isThumbsUp = false;
   }
 
   /**
-   * Creates a ThumbRating instance.
+   * Creates a rated instance.
    *
-   * @param thumbIsUp true for a "thumb up" rating, false for "thumb down".
+   * @param isThumbsUp {@code true} for "thumbs up", {@code false} for "thumbs down".
    */
-  public ThumbRating(boolean thumbIsUp) {
-    isRated = true;
-    thumbUp = thumbIsUp;
+  public ThumbRating(boolean isThumbsUp) {
+    rated = true;
+    this.isThumbsUp = isThumbsUp;
   }
 
   @Override
   public boolean isRated() {
-    return isRated;
+    return rated;
   }
 
   @Override
   public int hashCode() {
-    return Objects.hashCode(isRated, thumbUp);
+    return Objects.hashCode(rated, isThumbsUp);
   }
 
   @Override
@@ -67,42 +65,41 @@ public final class ThumbRating extends Rating {
       return false;
     }
     ThumbRating other = (ThumbRating) obj;
-    return thumbUp == other.thumbUp && isRated == other.isRated;
-  }
-
-  @Override
-  public String toString() {
-    return "ThumbRating: " + (isRated ? "isThumbUp=" + thumbUp : "unrated");
+    return isThumbsUp == other.isThumbsUp && rated == other.rated;
   }
 
   // Bundleable implementation.
+
+  @RatingType private static final int TYPE = RATING_TYPE_THUMB;
+
   @Documented
   @Retention(RetentionPolicy.SOURCE)
-  @IntDef({FIELD_RATING_TYPE, FIELD_IS_RATED, FIELD_IS_THUMB_UP})
+  @IntDef({FIELD_RATING_TYPE, FIELD_RATED, FIELD_IS_THUMBS_UP})
   private @interface FieldNumber {}
 
-  private static final int FIELD_IS_RATED = 1;
-  private static final int FIELD_IS_THUMB_UP = 2;
+  private static final int FIELD_RATED = 1;
+  private static final int FIELD_IS_THUMBS_UP = 2;
 
   @Override
   public Bundle toBundle() {
     Bundle bundle = new Bundle();
     bundle.putInt(keyForField(FIELD_RATING_TYPE), TYPE);
-    bundle.putBoolean(keyForField(FIELD_IS_RATED), isRated);
-    bundle.putBoolean(keyForField(FIELD_IS_THUMB_UP), thumbUp);
+    bundle.putBoolean(keyForField(FIELD_RATED), rated);
+    bundle.putBoolean(keyForField(FIELD_IS_THUMBS_UP), isThumbsUp);
     return bundle;
   }
 
+  /** Object that can restore a {@link ThumbRating} from a {@link Bundle}. */
   public static final Creator<ThumbRating> CREATOR = ThumbRating::fromBundle;
 
   private static ThumbRating fromBundle(Bundle bundle) {
     checkArgument(
         bundle.getInt(keyForField(FIELD_RATING_TYPE), /* defaultValue= */ RATING_TYPE_DEFAULT)
             == TYPE);
-    boolean isRated = bundle.getBoolean(keyForField(FIELD_IS_RATED), /* defaultValue= */ false);
-    return isRated
+    boolean rated = bundle.getBoolean(keyForField(FIELD_RATED), /* defaultValue= */ false);
+    return rated
         ? new ThumbRating(
-            bundle.getBoolean(keyForField(FIELD_IS_THUMB_UP), /* defaultValue= */ false))
+            bundle.getBoolean(keyForField(FIELD_IS_THUMBS_UP), /* defaultValue= */ false))
         : new ThumbRating();
   }
 

library/common/src/test/java/com/google/android/exoplayer2/RatingTest.java

@@ -39,7 +39,7 @@ public class RatingTest {
     boolean hasHeart = true;
     HeartRating rating = new HeartRating(hasHeart);
     assertThat(rating.isRated()).isTrue();
-    assertThat(rating.hasHeart).isEqualTo(hasHeart);
+    assertThat(rating.isHeart).isEqualTo(hasHeart);
     assertThat(roundTripViaBundle(rating)).isEqualTo(rating);
   }
 
@@ -71,7 +71,7 @@ public class RatingTest {
     boolean isThumbUp = true;
     ThumbRating rating = new ThumbRating(isThumbUp);
     assertThat(rating.isRated()).isTrue();
-    assertThat(rating.thumbUp).isEqualTo(isThumbUp);
+    assertThat(rating.isThumbsUp).isEqualTo(isThumbUp);
     assertThat(roundTripViaBundle(rating)).isEqualTo(rating);
   }