From 416bd435847ef8323116a2d382dcc10fc95ab3c7 Mon Sep 17 00:00:00 2001 From: gyumin Date: Mon, 3 May 2021 04:19:38 +0100 Subject: [PATCH] Revise javadoc for Rating classes PiperOrigin-RevId: 371625281 --- .../android/exoplayer2/HeartRating.java | 58 +++++++++---------- .../android/exoplayer2/PercentageRating.java | 26 ++++----- .../com/google/android/exoplayer2/Rating.java | 36 +++++++----- .../google/android/exoplayer2/StarRating.java | 43 ++++++-------- .../android/exoplayer2/ThumbRating.java | 57 +++++++++--------- .../google/android/exoplayer2/RatingTest.java | 4 +- 6 files changed, 107 insertions(+), 117 deletions(-) diff --git a/library/common/src/main/java/com/google/android/exoplayer2/HeartRating.java b/library/common/src/main/java/com/google/android/exoplayer2/HeartRating.java index e6610d6b7b..ff96ecd38c 100644 --- 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 - * 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 rated; - private final boolean isRated; + /** Whether the rating is "heart". */ + public final boolean isHeart; - /** Whether the rating has a heart rating or not. */ - public final boolean hasHeart; - - /** 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 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(); } diff --git a/library/common/src/main/java/com/google/android/exoplayer2/PercentageRating.java b/library/common/src/main/java/com/google/android/exoplayer2/PercentageRating.java index 1af82a57c3..3e078a0b3a 100644 --- 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 - * 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 CREATOR = PercentageRating::fromBundle; private static PercentageRating fromBundle(Bundle bundle) { diff --git a/library/common/src/main/java/com/google/android/exoplayer2/Rating.java b/library/common/src/main/java/com/google/android/exoplayer2/Rating.java index e80f033048..0477bbce0e 100644 --- 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; + /* 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; - // Default package-private constructor to prevent extending Rating class outside this package. - /* package */ Rating() {} - - /** 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 CREATOR = Rating::fromBundle; private static Rating fromBundle(Bundle bundle) { diff --git a/library/common/src/main/java/com/google/android/exoplayer2/StarRating.java b/library/common/src/main/java/com/google/android/exoplayer2/StarRating.java index af4b59ba1e..99e56a7d74 100644 --- 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; - - 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 CREATOR = StarRating::fromBundle; private static StarRating fromBundle(Bundle bundle) { diff --git a/library/common/src/main/java/com/google/android/exoplayer2/ThumbRating.java b/library/common/src/main/java/com/google/android/exoplayer2/ThumbRating.java index dbb2bcb791..bd56959bae 100644 --- 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 is "thumbs up". */ + public final boolean isThumbsUp; - /** Whether the rating has a thumb up or thumb down rating. */ - public final boolean thumbUp; - - /** 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 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(); } diff --git a/library/common/src/test/java/com/google/android/exoplayer2/RatingTest.java b/library/common/src/test/java/com/google/android/exoplayer2/RatingTest.java index 3c50f1cdcf..4c2d5b78b6 100644 --- 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); }