Add more documentation

Especially in and around LongPressAction.kt
Also add some logging / Toast when fetchAllAndShuffle() has to stop early

Author: Stypox

app/src/main/java/org/schabi/newpipe/fragments/list/BaseListFragment.java

@@ -295,6 +295,8 @@ public void selected(final ChannelInfoItem selectedItem) {
 
             @Override
             public void held(final ChannelInfoItem item) {
+                // Note: this does a blocking I/O call to the database. Use coroutines when
+                // migrating to Kotlin/Compose instead.
                 final boolean isSubscribed = new SubscriptionManager(requireContext())
                         .blockingIsSubscribed(item.getServiceId(), item.getUrl());
 
@@ -338,9 +340,9 @@ public void held(final PlaylistInfoItem selectedItem) {
 
     /**
      * @param item an item in the list, from which the built queue should start
-     * @return a builder for a queue containing all of the items in this list, with the queue index
-     * set to the item passed as parameter; return {@code null} if no "start playing from here"
-     * options should be shown
+     * @return a builder for a queue containing all of the streams items in this list, with the
+     * queue index set to the stream item passed as parameter; return {@code null} if no "start
+     * playing from here" options should be shown
      */
     @Nullable
     protected Function0<PlayQueue> getPlayQueueStartingAt(@NonNull final StreamInfoItem item) {

app/src/main/java/org/schabi/newpipe/local/bookmark/BookmarkFragment.java

@@ -491,6 +491,8 @@ private void showLocalDialog(final PlaylistMetadataEntry selectedItem) {
                 LongPressable.fromPlaylistMetadataEntry(selectedItem),
                 LongPressAction.fromPlaylistMetadataEntry(
                         selectedItem,
+                        // Note: this does a blocking I/O call to the database. Use coroutines when
+                        // migrating to Kotlin/Compose instead.
                         localPlaylistManager.getIsPlaylistThumbnailPermanent(selectedItem.getUid()),
                         // TODO passing this parameter is bad and should be fixed when migrating the
                         //  bookmark fragment to Compose, for more info see method javadoc

app/src/main/java/org/schabi/newpipe/local/playlist/LocalPlaylistFragment.java

@@ -584,6 +584,11 @@ private void changePlaylistName(final String title) {
         disposables.add(disposable);
     }
 
+    /**
+     * Changes the playlist's non-permanent thumbnail to the one of the stream entity with the
+     * provided ID, but only does so if the user did not set a permanent thumbnail themselves.
+     * @param thumbnailStreamId the ID of the stream entity whose thumbnail will be displayed
+     */
     private void changeThumbnailStreamIdIfNotPermanent(final long thumbnailStreamId) {
         if (playlistManager == null
                 || playlistManager.getIsPlaylistThumbnailPermanent(playlistId)) {

app/src/main/java/org/schabi/newpipe/local/subscription/SubscriptionManager.kt

@@ -119,6 +119,11 @@ class SubscriptionManager(context: Context) {
         subscriptionTable.delete(subscriptionEntity)
     }
 
+    /**
+     * Checks if the user is subscribed to a channel, in a blocking manner. Since the data being
+     * loaded from the database is very little, this should be fine. However once the migration to
+     * Kotlin coroutines will be finished, the blocking computation should be removed.
+     */
     fun blockingIsSubscribed(serviceId: Int, url: String): Boolean {
         return !subscriptionTable.getSubscription(serviceId, url).isEmpty.blockingGet()
     }

app/src/main/java/org/schabi/newpipe/player/playqueue/ChannelTabPlayQueue.java

@@ -19,28 +19,37 @@
 
 public final class ChannelTabPlayQueue extends AbstractInfoPlayQueue<ChannelTabInfo> {
 
+    /**
+     * The channel tab link handler.
+     * If null, it indicates that we have yet to fetch the channel info and choose a tab from it.
+     */
     @Nullable
-    ListLinkHandler linkHandler;
+    ListLinkHandler tabHandler;
 
     public ChannelTabPlayQueue(final int serviceId,
-                               final ListLinkHandler linkHandler,
+                               final ListLinkHandler tabHandler,
                                final Page nextPage,
                                final List<StreamInfoItem> streams,
                                final int index) {
-        super(serviceId, linkHandler.getUrl(), nextPage, streams, index);
-        this.linkHandler = linkHandler;
+        super(serviceId, tabHandler.getUrl(), nextPage, streams, index);
+        this.tabHandler = tabHandler;
     }
 
     public ChannelTabPlayQueue(final int serviceId,
                                final ListLinkHandler linkHandler) {
         this(serviceId, linkHandler, null, Collections.emptyList(), 0);
     }
 
-    // Plays the first
+    /**
+     * Plays the streams in the channel tab where {@link ChannelTabHelper#isStreamsTab} returns
+     * true, choosing the first such tab among the ones returned by {@code ChannelInfo.getTabs()}.
+     * @param serviceId the service ID of the channel
+     * @param channelUrl the channel URL
+     */
     public ChannelTabPlayQueue(final int serviceId,
                                final String channelUrl) {
         super(serviceId, channelUrl, null, Collections.emptyList(), 0);
-        linkHandler = null;
+        tabHandler = null;
     }
 
     @Override
@@ -51,31 +60,34 @@ protected String getTag() {
     @Override
     public void fetch() {
         if (isInitial) {
-            if (linkHandler == null) {
+            if (tabHandler == null) {
+                // we still have not chosen a tab, so we need to fetch the channel
                 ExtractorHelper.getChannelInfo(this.serviceId, this.baseUrl, false)
                         .flatMap(channelInfo -> {
-                            linkHandler = channelInfo.getTabs()
+                            tabHandler = channelInfo.getTabs()
                                     .stream()
                                     .filter(ChannelTabHelper::isStreamsTab)
                                     .findFirst()
                                     .orElseThrow(() -> new ExtractionException(
                                             "No playable channel tab found"));
 
                             return ExtractorHelper
-                                    .getChannelTab(this.serviceId, this.linkHandler, false);
+                                    .getChannelTab(this.serviceId, this.tabHandler, false);
                         })
                         .subscribeOn(Schedulers.io())
                         .observeOn(AndroidSchedulers.mainThread())
                         .subscribe(getHeadListObserver());
 
             } else {
-                ExtractorHelper.getChannelTab(this.serviceId, this.linkHandler, false)
+                // fetch the initial page of the channel tab
+                ExtractorHelper.getChannelTab(this.serviceId, this.tabHandler, false)
                         .subscribeOn(Schedulers.io())
                         .observeOn(AndroidSchedulers.mainThread())
                         .subscribe(getHeadListObserver());
             }
         } else {
-            ExtractorHelper.getMoreChannelTabItems(this.serviceId, this.linkHandler, this.nextPage)
+            // fetch the successive page of the channel tab
+            ExtractorHelper.getMoreChannelTabItems(this.serviceId, this.tabHandler, this.nextPage)
                     .subscribeOn(Schedulers.io())
                     .observeOn(AndroidSchedulers.mainThread())
                     .subscribe(getNextPageObserver());

app/src/main/java/org/schabi/newpipe/player/playqueue/LocalPlaylistPlayQueue.kt

@@ -9,6 +9,9 @@ import org.schabi.newpipe.NewPipeDatabase
 import org.schabi.newpipe.database.playlist.PlaylistMetadataEntry
 import org.schabi.newpipe.local.playlist.LocalPlaylistManager
 
+/**
+ * A play queue that fetches all of the items in a local playlist.
+ */
 class LocalPlaylistPlayQueue(info: PlaylistMetadataEntry) : PlayQueue(0, listOf()) {
     private val playlistId: Long = info.uid
     private var fetchDisposable: Disposable? = null

app/src/main/java/org/schabi/newpipe/player/playqueue/PlayQueue.kt

@@ -1,5 +1,9 @@
 package org.schabi.newpipe.player.playqueue
 
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import android.widget.Toast
 import io.reactivex.rxjava3.android.schedulers.AndroidSchedulers
 import io.reactivex.rxjava3.core.BackpressureStrategy
 import io.reactivex.rxjava3.core.Flowable
@@ -8,6 +12,9 @@ import java.io.Serializable
 import java.util.Collections
 import java.util.concurrent.atomic.AtomicInteger
 import kotlinx.coroutines.reactive.awaitFirst
+import org.schabi.newpipe.App
+import org.schabi.newpipe.BuildConfig
+import org.schabi.newpipe.R
 import org.schabi.newpipe.player.playqueue.PlayQueueEvent.AppendEvent
 import org.schabi.newpipe.player.playqueue.PlayQueueEvent.ErrorEvent
 import org.schabi.newpipe.player.playqueue.PlayQueueEvent.InitEvent
@@ -16,7 +23,6 @@ import org.schabi.newpipe.player.playqueue.PlayQueueEvent.RecoveryEvent
 import org.schabi.newpipe.player.playqueue.PlayQueueEvent.RemoveEvent
 import org.schabi.newpipe.player.playqueue.PlayQueueEvent.ReorderEvent
 import org.schabi.newpipe.player.playqueue.PlayQueueEvent.SelectEvent
-import org.schabi.newpipe.player.playqueue.PlayQueueItem
 
 /**
  * PlayQueue is responsible for keeping track of a list of streams and the index of
@@ -460,10 +466,29 @@ abstract class PlayQueue internal constructor(
                     // servers by making too many requests. For reference, making 10 fetch requests
                     // will mean fetching at most 1000 items on YouTube playlists, though this
                     // changes among services.
+                    Log.w(
+                        TAG,
+                        "Stopped after $MAX_FETCHES_BEFORE_SHUFFLING calls to fetch() " +
+                            "(for a total of ${streams.size} streams) to avoid rate limits"
+                    )
+                    Handler(Looper.getMainLooper()).post {
+                        Toast.makeText(
+                            App.instance,
+                            App.instance.getString(
+                                R.string.queue_fetching_stopped_early,
+                                MAX_FETCHES_BEFORE_SHUFFLING,
+                                streams.size
+                            ),
+                            Toast.LENGTH_SHORT
+                        ).show()
+                    }
                     break
                 }
                 fetchCount += 1
 
+                if (BuildConfig.DEBUG) {
+                    Log.d(TAG, "fetchAllAndShuffle(): fetching a page, current stream count ${streams.size}")
+                }
                 fetch()
 
                 // Since `fetch()` does not return a Completable we can listen on, we have to wait
@@ -562,4 +587,9 @@ abstract class PlayQueue internal constructor(
     private fun broadcast(event: PlayQueueEvent) {
         eventBroadcast?.onNext(event)
     }
+
+    companion object {
+        val TAG: String = PlayQueue::class.java.simpleName
+        const val MAX_FETCHES_BEFORE_SHUFFLING = 10
+    }
 }

app/src/main/java/org/schabi/newpipe/settings/VideoAudioSettingsFragment.java

@@ -52,6 +52,8 @@ public void onCreatePreferences(final Bundle savedInstanceState, final String ro
             } else if (getString(R.string.show_higher_resolutions_key).equals(key)) {
                 updateResolutionOptions();
             } else if (getString(R.string.show_play_with_kodi_key).equals(key)) {
+                // Adds or removes the kodi action from the long press menu (but the user may still
+                // remove/add it again independently of the show_play_with_kodi_key setting).
                 addOrRemoveKodiLongPressAction(requireContext());
             }
         };