Revise javadoc for Rating classes

PiperOrigin-RevId: 371625281

Revise javadoc for Rating classes
PiperOrigin-RevId: 371625281
416bd435 · gyumin · bachinger · f7a8c6e4 · 416bd435 · 416bd435
Commit 416bd435 authored May 03, 2021 by gyumin Committed by bachinger May 04, 2021
Showing with 107 additions and 117 deletions
library/common/src/main/java/com/google/android/exoplayer2/HeartRating.java
library/common/src/main/java/com/google/android/exoplayer2/PercentageRating.java
library/common/src/main/java/com/google/android/exoplayer2/Rating.java
library/common/src/main/java/com/google/android/exoplayer2/StarRating.java
library/common/src/main/java/com/google/android/exoplayer2/ThumbRating.java
library/common/src/test/java/com/google/android/exoplayer2/RatingTest.java
--- a/library/common/src/main/java/com/google/android/exoplayer2/HeartRating.java
+++ b/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
+ * A rating expressed as "heart" or "no heart". It can be used to indicate whether the content is a
- * indicate the content referred to is a favorite (or not).
+ * favorite.
 */
 public final class HeartRating extends Rating {
-  @RatingType private static final int TYPE = RATING_TYPE_HEART;
+  private final boolean rated;
-  private final boolean isRated;
-  /** Whether the rating has a heart rating or not. */
+  /** Whether the rating is "heart". */
-  public final boolean hasHeart;
+  public final boolean isHeart;
-  /** Creates a unrated HeartRating instance. */
+  /** Creates a unrated instance. */
  public HeartRating() {
-    isRated = false;
+    rated = false;
-    hasHeart = 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) {
+  public HeartRating(boolean isHeart) {
-    isRated = true;
+    rated = true;
-    this.hasHeart = hasHeart;
+    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;
+    return isHeart == other.isHeart && rated == other.rated;
-  }
-  @Override
-  public String toString() {
-    return "HeartRating: " + (isRated ? "hasHeart=" + hasHeart : "unrated");
  }
  // 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_RATED = 1;
-  private static final int FIELD_HAS_HEART = 2;
+  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_RATED), rated);
-    bundle.putBoolean(keyForField(FIELD_HAS_HEART), hasHeart);
+    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(
+        ? new HeartRating(bundle.getBoolean(keyForField(FIELD_IS_HEART), /* defaultValue= */ false))
-            bundle.getBoolean(keyForField(FIELD_HAS_HEART), /* defaultValue= */ false))
        : new HeartRating();
  }

--- a/library/common/src/main/java/com/google/android/exoplayer2/PercentageRating.java
+++ b/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
+   * The percent value of this rating. Will be within the range {@code [0f, 100f]}, or {@link
-   * it is unrated.
+   * #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
+   * Creates a rated instance with the given percentage.
-   * 0f or greater than 100f, it will throw IllegalArgumentException.
   *
-   * @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) {

--- a/library/common/src/main/java/com/google/android/exoplayer2/Rating.java
+++ b/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 {}
+  /* package */ @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;
-  // Default package-private constructor to prevent extending Rating class outside this package.
+  /* package */ static final int RATING_TYPE_DEFAULT = -1;
-  /* package */ Rating() {}
+  /* 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) {

--- a/library/common/src/main/java/com/google/android/exoplayer2/StarRating.java
+++ b/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;
+  /** The maximum number of stars. Must be a positive number. */
-  private static final int MAX_STARS_DEFAULT = 5;
-  /** The maximum number of stars for this rating. 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
+   * The fractional number of stars of this rating. Will range from {@code 0f} to {@link #maxStars},
-   * #RATING_UNSET} if it is unrated.
+   * or {@link #RATING_UNSET} if unrated.
   */
  public final float starRating;
  /**
-   * Creates a unrated StarRating instance with {@code maxStars}. If {@code maxStars} is not a
+   * Creates a unrated instance with {@code maxStars}. If {@code maxStars} is not a positive
-   * positive integer, it will throw IllegalArgumentException.
+   * 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
+   * Creates a rated instance with {@code maxStars} and the given fractional number of stars.
-   * of stars. Non-integer values can for instance be used to represent an average rating value,
+   * Non-integer values may be used to represent an average rating value. If {@code maxStars} is not
-   * which might not be an integer number of stars. If {@code maxStars} is not a positive integer or
+   * a positive integer or {@code starRating} is out of range, it will throw an {@link
-   * {@code starRating} has invalid value, it will throw IllegalArgumentException.
+   * IllegalArgumentException}.
   *
-   * @param maxStars the maximum number of stars which this rating can have.
+   * @param maxStars The maximum number of stars this rating can have.
-   * @param starRating a number ranging from 0.0f to {@code maxStars}
+   * @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) {

--- a/library/common/src/main/java/com/google/android/exoplayer2/ThumbRating.java
+++ b/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 rated;
-  private final boolean isRated;
-  /** Whether the rating has a thumb up or thumb down rating. */
+  /** Whether the rating is "thumbs up". */
-  public final boolean thumbUp;
+  public final boolean isThumbsUp;
-  /** Creates a unrated ThumbRating instance. */
+  /** Creates a unrated instance. */
  public ThumbRating() {
-    isRated = false;
+    rated = false;
-    thumbUp = 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) {
+  public ThumbRating(boolean isThumbsUp) {
-    isRated = true;
+    rated = true;
-    thumbUp = thumbIsUp;
+    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;
+    return isThumbsUp == other.isThumbsUp && rated == other.rated;
-  }
-  @Override
-  public String toString() {
-    return "ThumbRating: " + (isRated ? "isThumbUp=" + thumbUp : "unrated");
  }
  // 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_RATED = 1;
-  private static final int FIELD_IS_THUMB_UP = 2;
+  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_RATED), rated);
-    bundle.putBoolean(keyForField(FIELD_IS_THUMB_UP), thumbUp);
+    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);
+    boolean rated = bundle.getBoolean(keyForField(FIELD_RATED), /* defaultValue= */ false);
-    return isRated
+    return rated
        ? new ThumbRating(
-            bundle.getBoolean(keyForField(FIELD_IS_THUMB_UP), /* defaultValue= */ false))
+            bundle.getBoolean(keyForField(FIELD_IS_THUMBS_UP), /* defaultValue= */ false))
        : new ThumbRating();
  }

--- a/library/common/src/test/java/com/google/android/exoplayer2/RatingTest.java
+++ b/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);
  }