Apply reviews: improve comments, remove FILE, remove Stream#equals(Stream)

Author: Stypox

extractor/src/main/java/org/schabi/newpipe/extractor/services/media_ccc/extractors/MediaCCCLiveStreamExtractor.java

@@ -210,7 +210,7 @@ private <T extends Stream> List<T> getStreams(
                 // Ensure that we use only process JsonObjects
                 .filter(JsonObject.class::isInstance)
                 .map(JsonObject.class::cast)
-                // Only process audio streams
+                // Only process streams of requested type
                 .filter(streamJsonObj -> streamType.equals(streamJsonObj.getString("type")))
                 // Flatmap Urls and ensure that we use only process JsonObjects
                 .flatMap(streamJsonObj -> streamJsonObj.getObject(URLS).entrySet().stream()

extractor/src/main/java/org/schabi/newpipe/extractor/services/media_ccc/extractors/MediaCCCStreamExtractor.java

@@ -147,8 +147,8 @@ public List<VideoStream> getVideoStreams() throws ExtractionException {
                     mediaFormat = null;
                 }
 
-                // Don't use the containsSimilarStream method because it will remove the
-                // extraction of some video versions (mostly languages). So if there are multiple
+                // Don't use the containsSimilarStream method because it will prevent the
+                // extraction of some video variations (mostly languages). So if there are multiple
                 // video streams available, only the first one will be extracted in this case.
                 videoStreams.add(new VideoStream.Builder()
                         .setId(recording.getString("filename", ID_UNKNOWN))

extractor/src/main/java/org/schabi/newpipe/extractor/services/youtube/YoutubeParsingHelper.java

@@ -1264,8 +1264,8 @@ public static String getAndroidUserAgent(@Nullable final Localization localizati
         // Spoofing an Android 12 device with the hardcoded version of the Android app
         return "com.google.android.youtube/" + MOBILE_YOUTUBE_CLIENT_VERSION
                 + " (Linux; U; Android 12; "
-                + (localization != null ? localization.getCountryCode()
-                        : Localization.DEFAULT.getCountryCode())
+                + (localization == null ? Localization.DEFAULT.getCountryCode()
+                        : localization.getCountryCode())
                 + ") gzip";
     }
 

extractor/src/main/java/org/schabi/newpipe/extractor/stream/DeliveryMethod.java

@@ -7,14 +7,13 @@
 public enum DeliveryMethod {
 
     /**
-     * Enum constant which represents the use of the progressive HTTP streaming method to fetch a
-     * {@link Stream stream}.
+     * Used for {@link Stream}s served using the progressive HTTP streaming method.
      */
     PROGRESSIVE_HTTP,
 
     /**
-     * Enum constant which represents the use of the DASH (Dynamic Adaptive Streaming over HTTP)
-     * adaptive streaming method to fetch a {@link Stream stream}.
+     * Used for {@link Stream}s served using the DASH (Dynamic Adaptive Streaming over HTTP)
+     * adaptive streaming method.
      *
      * @see <a href="https://en.wikipedia.org/wiki/Dynamic_Adaptive_Streaming_over_HTTP">the
      * Dynamic Adaptive Streaming over HTTP Wikipedia page</a> and <a href="https://dashif.org/">
@@ -23,8 +22,8 @@ public enum DeliveryMethod {
     DASH,
 
     /**
-     * Enum constant which represents the use of the HLS (HTTP Live Streaming) adaptive streaming
-     * method to fetch a {@link Stream stream}.
+     * Used for {@link Stream}s served using the HLS (HTTP Live Streaming) adaptive streaming
+     * method.
      *
      * @see <a href="https://en.wikipedia.org/wiki/HTTP_Live_Streaming">the HTTP Live Streaming
      * page</a> and <a href="https://developer.apple.com/streaming">Apple's developers website page
@@ -33,8 +32,7 @@ public enum DeliveryMethod {
     HLS,
 
     /**
-     * Enum constant which represents the use of the SmoothStreaming adaptive streaming method to
-     * fetch a {@link Stream stream}.
+     * Used for {@link Stream}s served using the SmoothStreaming adaptive streaming method.
      *
      * @see <a href="https://en.wikipedia.org/wiki/Adaptive_bitrate_streaming
      * #Microsoft_Smooth_Streaming_(MSS)">Wikipedia's page about adaptive bitrate streaming,
@@ -44,7 +42,7 @@ public enum DeliveryMethod {
     SS,
 
     /**
-     * Enum constant which represents the use of a torrent file to fetch a {@link Stream stream}.
+     * Used for {@link Stream}s served via a torrent file.
      *
      * @see <a href="https://en.wikipedia.org/wiki/BitTorrent">Wikipedia's BitTorrent's page</a>,
      * <a href="https://en.wikipedia.org/wiki/Torrent_file">Wikipedia's page about torrent files

extractor/src/main/java/org/schabi/newpipe/extractor/stream/Stream.java

@@ -115,19 +115,6 @@ public boolean equalStats(@Nullable final Stream cmp) {
                 : areUsingSameDeliveryMethodAndAreUrlStreams;
     }
 
-    /**
-     * Reveals whether two streams are equal.
-     *
-     * @param cmp a {@link Stream} object to be compared to this {@link Stream} instance.
-     * @return whether the compared streams are equal
-     * @deprecated Use {@link #equalStats(Stream)} to compare statistics of two streams and
-     * {@link #equals(Object)} to compare the equality of two streams instead.
-     */
-    @Deprecated
-    public boolean equals(final Stream cmp) {
-        return equalStats(cmp) && content.equals(cmp.content);
-    }
-
     /**
      * Gets the identifier of this stream, e.g. the itag for YouTube.
      *

extractor/src/main/java/org/schabi/newpipe/extractor/stream/StreamType.java

@@ -1,114 +1,74 @@
 package org.schabi.newpipe.extractor.stream;
 
 /**
- * An enum representing the stream types of stream contents returned by the extractor.
+ * An enum representing the stream type of a {@link StreamInfo} extracted by a {@link
+ * StreamExtractor}.
  */
 public enum StreamType {
 
     /**
-     * Placeholder to check if the stream type of stream content was checked or not.
-     *
-     * <p>
-     * It doesn't make sense to use this enum constant outside of the extractor as it will never be
-     * returned by an {@link org.schabi.newpipe.extractor.Extractor extractor} and is only used
-     * internally.
-     * </p>
+     * Placeholder to check if the stream type was checked or not. It doesn't make sense to use this
+     * enum constant outside of the extractor as it will never be returned by an {@link
+     * org.schabi.newpipe.extractor.Extractor} and is only used internally.
      */
     NONE,
 
     /**
-     * Enum constant to indicate that the stream type of stream content is a live video.
-     *
-     * <p>
-     * Note that contents <strong>may contain audio streams</strong> even if they also contain
-     * video streams (video-only or video with audio, depending of the stream/the content/the
-     * service).
-     * </p>
+     * A normal video stream, usually with audio. Note that the {@link StreamInfo} <strong>can also
+     * provide audio-only {@link AudioStream}s</strong> in addition to video or video-only {@link
+     * VideoStream}s.
      */
     VIDEO_STREAM,
 
     /**
-     * Enum constant to indicate that the stream type of stream content is an audio.
-     *
-     * <p>
-     * Note that contents returned as audio streams should not return video streams.
-     * </p>
-     *
-     * <p>
-     * So, in order to prevent unexpected behaviors, stream extractors which are returning this
-     * stream type for a content should ensure that no video stream is returned for this content.
-     * </p>
+     * An audio-only stream. There should be no {@link VideoStream}s available! In order to prevent
+     * unexpected behaviors, when {@link StreamExtractor}s return this stream type, they should
+     * ensure that no video stream is returned in {@link StreamExtractor#getVideoStreams()} and
+     * {@link StreamExtractor#getVideoOnlyStreams()}.
      */
     AUDIO_STREAM,
 
     /**
-     * Enum constant to indicate that the stream type of stream content is a video.
-     *
-     * <p>
-     * Note that contents <strong>can contain audio live streams</strong> even if they also contain
-     * live video streams (so video-only or video with audio, depending on the stream/the content/
-     * the service).
-     * </p>
+     * A video live stream, usually with audio. Note that the {@link StreamInfo} <strong>can also
+     * provide audio-only {@link AudioStream}s</strong> in addition to video or video-only {@link
+     * VideoStream}s.
      */
     LIVE_STREAM,
 
     /**
-     * Enum constant to indicate that the stream type of stream content is a live audio.
-     *
-     * <p>
-     * Note that contents returned as live audio streams should not return live video streams.
-     * </p>
-     *
-     * <p>
-     * To prevent unexpected behavior, stream extractors which are returning this stream type for a
-     * content should ensure that no live video stream is returned along with it.
-     * </p>
+     * An audio-only live stream. There should be no {@link VideoStream}s available! In order to
+     * prevent unexpected behaviors, when {@link StreamExtractor}s return this stream type, they
+     * should ensure that no video stream is returned in {@link StreamExtractor#getVideoStreams()}
+     * and {@link StreamExtractor#getVideoOnlyStreams()}.
      */
     AUDIO_LIVE_STREAM,
 
     /**
-     * Enum constant to indicate that the stream type of stream content is a video content of an
-     * ended live video stream.
+     * A video live stream that has just ended but has not yet been encoded into a normal video
+     * stream. Note that the {@link StreamInfo} <strong>can also provide audio-only {@link
+     * AudioStream}s</strong> in addition to video or video-only {@link VideoStream}s.
      *
      * <p>
      * Note that most of the content of an ended live video (or audio) may be extracted as {@link
      * #VIDEO_STREAM regular video contents} (or {@link #AUDIO_STREAM regular audio contents})
      * later, because the service may encode them again later as normal video/audio streams. That's
      * the case on YouTube, for example.
      * </p>
-     *
-     * <p>
-     * Note that contents <strong>can contain post-live audio streams</strong> even if they also
-     * contain post-live video streams (video-only or video with audio, depending of the stream/the
-     * content/the service).
-     * </p>
      */
     POST_LIVE_STREAM,
 
     /**
-     * Enum constant to indicate that the stream type of stream content is an audio content of an
-     * ended live audio stream.
+     * An audio live stream that has just ended but has not yet been encoded into a normal audio
+     * stream. There should be no {@link VideoStream}s available! In order to prevent unexpected
+     * behaviors, when {@link StreamExtractor}s return this stream type, they should ensure that no
+     * video stream is returned in {@link StreamExtractor#getVideoStreams()} and
+     * {@link StreamExtractor#getVideoOnlyStreams()}.
      *
      * <p>
      * Note that most of ended live audio streams extracted with this value are processed as
      * {@link #AUDIO_STREAM regular audio streams} later, because the service may encode them
      * again later.
      * </p>
-     *
-     * <p>
-     * Contents returned as post-live audio streams should not return post-live video streams.
-     * </p>
-     *
-     * <p>
-     * So, in order to prevent unexpected behaviors, stream extractors which are returning this
-     * stream type for a content should ensure that no post-live video stream is returned for this
-     * content.
-     * </p>
-     */
-    POST_LIVE_AUDIO_STREAM,
-
-    /**
-     * Enum constant to indicate that the stream type of stream content is a file.
      */
-    FILE
+    POST_LIVE_AUDIO_STREAM
 }

extractor/src/main/java/org/schabi/newpipe/extractor/utils/ManifestCreatorCache.java

@@ -141,17 +141,13 @@ public void reset() {
     }
 
     /**
-     * Returns the number of cached manifests in the cache.
-     *
-     * @return the number of cached manifests
+     * @return the number of cached manifests in the cache
      */
     public int size() {
         return concurrentHashMap.size();
     }
 
     /**
-     * Gets the maximum size of the cache.
-     *
      * @return the maximum size of the cache
      */
     public long getMaximumSize() {
@@ -188,9 +184,7 @@ public void resetMaximumSize() {
     }
 
     /**
-     * Gets the current clear factor of the cache, used when the cache limit size is reached.
-     *
-     * @return the current clear factor of the cache
+     * @return the current clear factor of the cache, used when the cache limit size is reached
      */
     public double getClearFactor() {
         return clearFactor;