From 3455f0f23c6e34a16e23bdb687037ea3849697f8 Mon Sep 17 00:00:00 2001
From: XiangRongLin <41164160+XiangRongLin@users.noreply.github.com>
Date: Tue, 12 Jan 2021 09:37:48 +0100
Subject: [PATCH] Add documentation to testing with mocks

---
 .../newpipe/downloader/DownloaderFactory.java   | 14 ++++++++++++++
 .../newpipe/downloader/MockDownloader.java      |  5 +++++
 .../newpipe/downloader/RecordingDownloader.java | 17 +++++++++++++++++
 3 files changed, 36 insertions(+)

diff --git a/extractor/src/test/java/org/schabi/newpipe/downloader/DownloaderFactory.java b/extractor/src/test/java/org/schabi/newpipe/downloader/DownloaderFactory.java
index c6fe2b2a6..0ffd38739 100644
--- a/extractor/src/test/java/org/schabi/newpipe/downloader/DownloaderFactory.java
+++ b/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}
      */
diff --git a/extractor/src/test/java/org/schabi/newpipe/downloader/MockDownloader.java b/extractor/src/test/java/org/schabi/newpipe/downloader/MockDownloader.java
index 20395b3ce..21019a4ec 100644
--- a/extractor/src/test/java/org/schabi/newpipe/downloader/MockDownloader.java
+++ b/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;
diff --git a/extractor/src/test/java/org/schabi/newpipe/downloader/RecordingDownloader.java b/extractor/src/test/java/org/schabi/newpipe/downloader/RecordingDownloader.java
index 0ba1a9935..bfe9e8c77 100644
--- a/extractor/src/test/java/org/schabi/newpipe/downloader/RecordingDownloader.java
+++ b/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);