From fc8321de1736e275218fafa713bebbc2beaada10 Mon Sep 17 00:00:00 2001
From: Hans-Christoph Steiner <hans@eds.org>
Date: Wed, 3 Mar 2021 10:06:32 +0100
Subject: [PATCH] javadoc for cache cleanup operations

---
 .../org/fdroid/fdroid/installer/ApkFileProvider.java |  5 ++++-
 .../org/fdroid/fdroid/work/CleanCacheWorker.java     | 12 ++++++++++++
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/app/src/main/java/org/fdroid/fdroid/installer/ApkFileProvider.java b/app/src/main/java/org/fdroid/fdroid/installer/ApkFileProvider.java
index e84cd52eb..b0dd65514 100644
--- a/app/src/main/java/org/fdroid/fdroid/installer/ApkFileProvider.java
+++ b/app/src/main/java/org/fdroid/fdroid/installer/ApkFileProvider.java
@@ -42,13 +42,16 @@ import java.io.IOException;
  * <i>"/Android/data/[app_package_name]/cache/apks"</i> (if card is mounted and app has
  * appropriate permission) or on device's file system depending incoming parameters</li>
  * <li>Before installation, the APK is copied into the private data directory of the F-Droid,
- * <i>"/data/data/[app_package_name]/files/install-$random.apk"</i></li>
+ * <i>"/data/data/[app_package_name]/files/install-$random.apk"</i> so that the install
+ * process broken if the user clears the cache while it is running.</li>
  * <li>The hash of the file is checked against the expected hash from the repository</li>
  * <li>For {@link Build.VERSION_CODES#M < android-23}, a {@code file://} {@link Uri}
  * pointing to the {@link File} is returned, for {@link Build.VERSION_CODES#M >= android-23},
  * a {@code content://} {@code Uri} is returned using support lib's
  * {@link FileProvider}</li>
  * </ol>
+ *
+ * @see org.fdroid.fdroid.work.CleanCacheWorker
  */
 public class ApkFileProvider extends FileProvider {
 
diff --git a/app/src/main/java/org/fdroid/fdroid/work/CleanCacheWorker.java b/app/src/main/java/org/fdroid/fdroid/work/CleanCacheWorker.java
index c28f37925..022af65b1 100644
--- a/app/src/main/java/org/fdroid/fdroid/work/CleanCacheWorker.java
+++ b/app/src/main/java/org/fdroid/fdroid/work/CleanCacheWorker.java
@@ -22,6 +22,18 @@ import org.fdroid.fdroid.installer.ApkCache;
 import java.io.File;
 import java.util.concurrent.TimeUnit;
 
+/**
+ * Deletes the built-up cruft left over from various processes.
+ * <p>
+ * The installation process downloads APKs to the cache, then when an APK is being
+ * installed, it is copied into files for running the install. Installs can happen
+ * fully in the background, so the user might clear the cache at any time, so the
+ * APK cannot be installed from the cache. Also, F-Droid is not guaranteed to get
+ * an event after the APK is installed, so that can't be used to delete the APK
+ * from files when it is no longer needed. That's where CleanCacheWorker comes in,
+ * it runs regularly to ensure things are cleaned up. If something blocks it from
+ * running, then APKs can remain in {@link org.fdroid.fdroid.installer.ApkFileProvider}
+ */
 public class CleanCacheWorker extends Worker {
     public static final String TAG = "CleanCacheWorker";