Add documentation to testing with mocks

extractor/src/test/java/org/schabi/newpipe/downloader/DownloaderFactory.java

@@ -11,6 +11,20 @@ public class DownloaderFactory {
     private final static DownloaderType DEFAULT_DOWNLOADER = DownloaderType.REAL;
 
     /**
+     * <p>
+     * Returns a implementation of a downloader.
+     * </p>
+     * <p>
+     * If the system property "downloader" is set and is one of {@link DownloaderType},
+     * then a downloader of that type is returned.
+     * It can be passed in with gradle by adding the argument -Ddownloader=abcd,
+     * where abcd is one of {@link DownloaderType}
+     * </p>
+     * <p>
+     * Otherwise it falls back to {@link DownloaderFactory#DEFAULT_DOWNLOADER}.
+     * Change this during development on the local machine to use a different downloader.
+     * </p>
+     *
      * @param path The path to the folder where mocks are saved/retrieved.
      *             Preferably starting with {@link DownloaderFactory#RESOURCE_PATH}
      */

extractor/src/test/java/org/schabi/newpipe/downloader/MockDownloader.java

@@ -14,6 +14,11 @@ import java.util.Map;
 
 import javax.annotation.Nonnull;
 
+/**
+ * <p>
+ * Mocks requests by using json files created by {@link RecordingDownloader}
+ * </p>
+ */
 class MockDownloader extends Downloader {
 
     private final String path;

extractor/src/test/java/org/schabi/newpipe/downloader/RecordingDownloader.java

@@ -16,6 +16,18 @@ import java.nio.file.Paths;
 
 import javax.annotation.Nonnull;
 
+/**
+ * <p>
+ * Relays requests to {@link DownloaderTestImpl} and saves the request/response pair into a json file.
+ * </p>
+ * <p>
+ * Those files are used by {@link MockDownloader}.
+ * </p>
+ * <p>
+ * The files <b>must</b> be created on the local dev environment
+ * and recreated when the requests made by a test class change.
+ * </p>
+ */
 class RecordingDownloader extends Downloader {
 
     public final static String FILE_NAME_PREFIX = "generated_mock_";
@@ -23,6 +35,11 @@ class RecordingDownloader extends Downloader {
     private int index = 0;
     private final String path;
 
+    /**
+     * Creates the folder described by {@code stringPath} if it does not exists.
+     * Deletes existing files starting with {@link RecordingDownloader#FILE_NAME_PREFIX}.
+     * @param stringPath Path to the folder where the json files will be saved to.
+     */
     public RecordingDownloader(String stringPath) throws IOException {
         this.path = stringPath;
         Path path = Paths.get(stringPath);