Add javadoc to installer classes

app/src/main/java/org/fdroid/fdroid/installer/DefaultInstaller.java

@@ -29,6 +29,13 @@ import org.fdroid.fdroid.Utils;
 
 import java.io.File;
 
+/**
+ * The default installer of F-Droid. It uses the normal Intents APIs of Android
+ * to install apks. Its main inner workings are encapsulated in DefaultInstallerActivity.
+ * <p/>
+ * This is installer requires user interaction and thus install/uninstall directly
+ * return PendingIntents.
+ */
 public class DefaultInstaller extends Installer {
 
     private static final String TAG = "DefaultInstaller";

app/src/main/java/org/fdroid/fdroid/installer/DefaultInstallerActivity.java

@@ -33,7 +33,7 @@ import android.util.Log;
 import org.fdroid.fdroid.R;
 
 /**
- * A transparent activity as a wrapper around AOSP's PackageInstaller Intents
+ * A transparent activity as a wrapper around Android's PackageInstaller Intents
  */
 public class DefaultInstallerActivity extends FragmentActivity {
     public static final String TAG = "AndroidInstallerAct";

app/src/main/java/org/fdroid/fdroid/installer/ExtensionInstaller.java

@@ -32,6 +32,10 @@ import java.io.File;
 
 /**
  * Special Installer that is only useful to install the Privileged Extension apk
+ * as a privileged app into the system partition of Android.
+ * <p/>
+ * This is installer requires user interaction and thus install/uninstall directly
+ * return PendingIntents.
  */
 public class ExtensionInstaller extends Installer {
 

app/src/main/java/org/fdroid/fdroid/installer/Installer.java

@@ -45,6 +45,9 @@ import java.io.IOException;
 import java.security.NoSuchAlgorithmException;
 import java.util.Map;
 
+/**
+ *
+ */
 public abstract class Installer {
     final Context context;
     final PackageManager pm;
@@ -64,10 +67,10 @@ public abstract class Installer {
      * Same as http://developer.android.com/reference/android/content/Intent.html#EXTRA_ORIGINATING_URI
      * In InstallManagerService often called urlString
      */
-    public static final String EXTRA_ORIGINATING_URI = "org.fdroid.fdroid.installer.InstallerService.extra.ORIGINATING_URI";
+    public static final String EXTRA_ORIGINATING_URI = "org.fdroid.fdroid.installer.Installer.extra.ORIGINATING_URI";
-    public static final String EXTRA_PACKAGE_NAME = "org.fdroid.fdroid.installer.InstallerService.extra.PACKAGE_NAME";
+    public static final String EXTRA_PACKAGE_NAME = "org.fdroid.fdroid.installer.Installer.extra.PACKAGE_NAME";
-    public static final String EXTRA_USER_INTERACTION_PI = "org.fdroid.fdroid.installer.InstallerService.extra.USER_INTERACTION_PI";
+    public static final String EXTRA_USER_INTERACTION_PI = "org.fdroid.fdroid.installer.Installer.extra.USER_INTERACTION_PI";
-    public static final String EXTRA_ERROR_MESSAGE = "org.fdroid.fdroid.net.Downloader.extra.ERROR_MESSAGE";
+    public static final String EXTRA_ERROR_MESSAGE = "org.fdroid.fdroid.net.installer.Installer.extra.ERROR_MESSAGE";
 
     public static class InstallFailedException extends Exception {
 
@@ -155,6 +158,14 @@ public abstract class Installer {
         return Uri.fromFile(sanitizedApkFile);
     }
 
+    /**
+     * Returns permission screen for given apk.
+     *
+     * @param apk instance of Apk
+     * @return Intent with Activity to show required permissions.
+     * Returns null if Installer handles that on itself, e.g., with DefaultInstaller,
+     * or if no new permissions have been introduced during an update
+     */
     public Intent getPermissionScreen(Apk apk) {
         if (!isUnattended()) {
             return null;
@@ -195,6 +206,15 @@ public abstract class Installer {
         return perms.getPermissionCount(AppSecurityPermissions.WHICH_ALL);
     }
 
+    /**
+     * Returns an Intent to start a dialog wrapped in an activity
+     * for uninstall confirmation.
+     *
+     * @param packageName packageName of app to uninstall
+     * @return Intent with activity for uninstall confirmation
+     * Returns null if Installer handles that on itself, e.g.,
+     * with DefaultInstaller.
+     */
     public Intent getUninstallScreen(String packageName) {
         if (!isUnattended()) {
             return null;

app/src/main/java/org/fdroid/fdroid/installer/InstallerFactory.java

@@ -29,15 +29,23 @@ public class InstallerFactory {
 
     private static final String TAG = "InstallerFactory";
 
-    public static Installer create(Context context) {
+    /**
-        return create(context, null);
+     * Returns an instance of an appropriate installer.
-    }
+     * Either DefaultInstaller, PrivilegedInstaller, or in the special
-
+     * case to install the "F-Droid Privileged Extension" ExtensionInstaller.
+     *
+     * @param context     current {@link Context}
+     * @param packageName package name of apk to be installed. Required to select
+     *                    the ExtensionInstaller.
+     *                    If this is null, the ExtensionInstaller will never be returned.
+     * @return instance of an Installer
+     */
     public static Installer create(Context context, String packageName) {
         Installer installer;
 
-        if (packageName != null && packageName.equals(PrivilegedInstaller.PRIVILEGED_EXTENSION_PACKAGE_NAME)) {
+        if (packageName != null
-            // special case: F-Droid Privileged Extension
+                && packageName.equals(PrivilegedInstaller.PRIVILEGED_EXTENSION_PACKAGE_NAME)) {
+            // special case for "F-Droid Privileged Extension"
             installer = new ExtensionInstaller(context);
         } else if (isPrivilegedInstallerEnabled()) {
             if (PrivilegedInstaller.isExtensionInstalledCorrectly(context)

app/src/main/java/org/fdroid/fdroid/installer/InstallerService.java

@@ -24,6 +24,16 @@ import android.content.Context;
 import android.content.Intent;
 import android.net.Uri;
 
+/**
+ * This service handles the install process of apk files and
+ * uninstall process of apps.
+ * <p/>
+ * This service is based on an IntentService because:
+ * - no parallel installs/uninstalls should be allowed,
+ * i.e., runs sequentially
+ * - no cancel operation is needed. Cancelling an installation
+ * would be the same as starting uninstall afterwards
+ */
 public class InstallerService extends IntentService {
 
     private static final String ACTION_INSTALL = "org.fdroid.fdroid.installer.InstallerService.action.INSTALL";
@@ -48,6 +58,14 @@ public class InstallerService extends IntentService {
         }
     }
 
+    /**
+     * Install an apk from {@link Uri}
+     *
+     * @param context        this app's {@link Context}
+     * @param uri            {@link Uri} pointing to (downloaded) local apk file
+     * @param originatingUri {@link Uri} where the apk has been downloaded from
+     * @param packageName    package name of the app that should be installed
+     */
     public static void install(Context context, Uri uri, Uri originatingUri, String packageName) {
         Intent intent = new Intent(context, InstallerService.class);
         intent.setAction(ACTION_INSTALL);
@@ -57,6 +75,12 @@ public class InstallerService extends IntentService {
         context.startService(intent);
     }
 
+    /**
+     * Uninstall an app
+     *
+     * @param context     this app's {@link Context}
+     * @param packageName package name of the app that will be uninstalled
+     */
     public static void uninstall(Context context, String packageName) {
         Intent intent = new Intent(context, InstallerService.class);
         intent.setAction(ACTION_UNINSTALL);

app/src/main/java/org/fdroid/fdroid/installer/PrivilegedInstaller.java

@@ -41,16 +41,21 @@ import org.fdroid.fdroid.privileged.IPrivilegedService;
 import java.util.HashMap;
 
 /**
- * Installer based on using internal hidden APIs of the Android OS, which are
+ * Installer that only works if the "F-Droid Privileged
- * protected by the permissions
+ * Extension" is installed as a privileged app.
- * <ul>
- * <li>android.permission.INSTALL_PACKAGES</li>
- * <li>android.permission.DELETE_PACKAGES</li>
- * </ul>
  * <p/>
+ * "F-Droid Privileged Extension" provides a service that exposes
+ * internal Android APIs for install/uninstall which are protected
+ * by INSTALL_PACKAGES, DELETE_PACKAGES permissions.
  * Both permissions are protected by systemOrSignature (in newer versions:
- * system|signature). Thus, this installer works only when the "F-Droid Privileged
+ * system|signature) and cannot be used directly by F-Droid.
- * Extension" is installed into the system.
+ * <p/>
+ * Instead, this installer binds to the service of
+ * "F-Droid Privileged Extension" and then executes the appropriate methods
+ * inside the privileged context of the privileged extension.
+ * <p/>
+ * This installer makes unattended installs/uninstalls possible.
+ * Thus no PendingIntents are returned.
  * <p/>
  * Sources for Android 4.4 change:
  * https://groups.google.com/forum/#!msg/android-
@@ -268,7 +273,6 @@ public class PrivilegedInstaller extends Installer {
     }
 
     public static int isExtensionInstalledCorrectly(Context context) {
-
         // check if installed
         if (!isExtensionInstalled(context)) {
             return IS_EXTENSION_INSTALLED_NO;