Extend documentation, proper method naming, use of deprecated method annotation

3 files changed, 38 insertions, 43 deletions

diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/remote/ApiPendingIntentFactory.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/remote/ApiPendingIntentFactory.java
index 3ebb8b638..4a37af491 100644
--- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/remote/ApiPendingIntentFactory.java
+++ b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/remote/ApiPendingIntentFactory.java
@@ -55,11 +55,11 @@ public class ApiPendingIntentFactory {
             case NFC_MOVE_KEY_TO_CARD:
             case NFC_DECRYPT:
             case NFC_SIGN: {
-                return nfc(requiredInput, cryptoInput);
+                return createNfcOperationPendingIntent(requiredInput, cryptoInput);
             }
 
             case PASSPHRASE: {
-                return passphrase(requiredInput, cryptoInput);
+                return createPassphrasePendingIntent(requiredInput, cryptoInput);
             }
 
             default:
@@ -67,84 +67,82 @@ public class ApiPendingIntentFactory {
         }
     }
 
-    private PendingIntent nfc(RequiredInputParcel requiredInput, CryptoInputParcel cryptoInput) {
+    private PendingIntent createNfcOperationPendingIntent(RequiredInputParcel requiredInput, CryptoInputParcel cryptoInput) {
         Intent intent = new Intent(mContext, RemoteSecurityTokenOperationActivity.class);
         // pass params through to activity that it can be returned again later to repeat pgp operation
         intent.putExtra(RemoteSecurityTokenOperationActivity.EXTRA_REQUIRED_INPUT, requiredInput);
         intent.putExtra(RemoteSecurityTokenOperationActivity.EXTRA_CRYPTO_INPUT, cryptoInput);
 
-        return build(intent);
+        return createInternal(intent);
     }
 
-    private PendingIntent passphrase(RequiredInputParcel requiredInput, CryptoInputParcel cryptoInput) {
+    private PendingIntent createPassphrasePendingIntent(RequiredInputParcel requiredInput, CryptoInputParcel cryptoInput) {
         Intent intent = new Intent(mContext, RemotePassphraseDialogActivity.class);
         // pass params through to activity that it can be returned again later to repeat pgp operation
         intent.putExtra(RemotePassphraseDialogActivity.EXTRA_REQUIRED_INPUT, requiredInput);
         intent.putExtra(RemotePassphraseDialogActivity.EXTRA_CRYPTO_INPUT, cryptoInput);
 
-        return build(intent);
+        return createInternal(intent);
     }
 
-    PendingIntent selectPublicKey(long[] keyIdsArray, ArrayList<String> missingEmails,
-                                  ArrayList<String> duplicateEmails, boolean noUserIdsCheck) {
+    PendingIntent createSelectPublicKeyPendingIntent(long[] keyIdsArray, ArrayList<String> missingEmails,
+                                                     ArrayList<String> duplicateEmails, boolean noUserIdsCheck) {
         Intent intent = new Intent(mContext, RemoteSelectPubKeyActivity.class);
         intent.putExtra(RemoteSelectPubKeyActivity.EXTRA_SELECTED_MASTER_KEY_IDS, keyIdsArray);
         intent.putExtra(RemoteSelectPubKeyActivity.EXTRA_NO_USER_IDS_CHECK, noUserIdsCheck);
         intent.putExtra(RemoteSelectPubKeyActivity.EXTRA_MISSING_EMAILS, missingEmails);
         intent.putExtra(RemoteSelectPubKeyActivity.EXTRA_DUPLICATE_EMAILS, duplicateEmails);
 
-        return build(intent);
+        return createInternal(intent);
     }
 
-    PendingIntent importFromKeyserver(long masterKeyId) {
+    PendingIntent createImportFromKeyserverPendingIntent(long masterKeyId) {
         Intent intent = new Intent(mContext, RemoteImportKeysActivity.class);
         intent.setAction(RemoteImportKeysActivity.ACTION_IMPORT_KEY_FROM_KEYSERVER_AND_RETURN_RESULT);
         intent.putExtra(RemoteImportKeysActivity.EXTRA_KEY_ID, masterKeyId);
 
-        return build(intent);
+        return createInternal(intent);
     }
 
-    PendingIntent selectAllowedKeys(String packageName) {
+    PendingIntent createSelectAllowedKeysPendingIntent(String packageName) {
         Intent intent = new Intent(mContext, SelectAllowedKeysActivity.class);
         intent.setData(KeychainContract.ApiApps.buildByPackageNameUri(packageName));
 
-        return build(intent);
+        return createInternal(intent);
     }
 
-    PendingIntent showKey(long masterKeyId) {
+    PendingIntent createShowKeyPendingIntent(long masterKeyId) {
         Intent intent = new Intent(mContext, ViewKeyActivity.class);
         intent.setData(KeychainContract.KeyRings.buildGenericKeyRingUri(masterKeyId));
 
-        return build(intent);
+        return createInternal(intent);
     }
 
-    PendingIntent selectSignKeyId(String packageName, String preferredUserId) {
+    PendingIntent createSelectSignKeyIdPendingIntent(String packageName, String preferredUserId) {
         Intent intent = new Intent(mContext, SelectSignKeyIdActivity.class);
         intent.setData(KeychainContract.ApiApps.buildByPackageNameUri(packageName));
         intent.putExtra(SelectSignKeyIdActivity.EXTRA_USER_ID, preferredUserId);
 
-        return build(intent);
+        return createInternal(intent);
     }
 
-    /**
-     * @deprecated
-     */
-    PendingIntent createAccount(String packageName, String accountName) {
+    @Deprecated
+    PendingIntent createAccountCreationPendingIntent(String packageName, String accountName) {
         Intent intent = new Intent(mContext, RemoteCreateAccountActivity.class);
         intent.putExtra(RemoteCreateAccountActivity.EXTRA_PACKAGE_NAME, packageName);
         intent.putExtra(RemoteCreateAccountActivity.EXTRA_ACC_NAME, accountName);
 
-        return build(intent);
+        return createInternal(intent);
     }
 
-    PendingIntent error(String errorMessage) {
+    PendingIntent createErrorPendingIntent(String errorMessage) {
         Intent intent = new Intent(mContext, RemoteErrorActivity.class);
         intent.putExtra(RemoteErrorActivity.EXTRA_ERROR_MESSAGE, errorMessage);
 
-        return build(intent);
+        return createInternal(intent);
     }
 
-    private PendingIntent build(Intent intent) {
+    private PendingIntent createInternal(Intent intent) {
         // re-attach "data" for pass through. It will be used later to repeat pgp operation
         intent.putExtra(RemoteSecurityTokenOperationActivity.EXTRA_DATA, mPendingIntentData);
 
@@ -160,7 +158,7 @@ public class ApiPendingIntentFactory {
         }
     }
 
-    PendingIntent register(String packageName, byte[] packageCertificate) {
+    PendingIntent createRegisterPendingIntent(String packageName, byte[] packageCertificate) {
         Intent intent = new Intent(mContext, RemoteRegisterActivity.class);
         intent.putExtra(RemoteRegisterActivity.EXTRA_PACKAGE_NAME, packageName);
         intent.putExtra(RemoteRegisterActivity.EXTRA_PACKAGE_SIGNATURE, packageCertificate);
diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/remote/ApiPermissionHelper.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/remote/ApiPermissionHelper.java
index 34dab6ec1..c08cf99a3 100644
--- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/remote/ApiPermissionHelper.java
+++ b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/remote/ApiPermissionHelper.java
@@ -95,7 +95,7 @@ public class ApiPermissionHelper {
                 }
                 Log.e(Constants.TAG, "Not allowed to use service! return PendingIntent for registration!");
 
-                PendingIntent pi = piFactory.register(packageName, packageCertificate);
+                PendingIntent pi = piFactory.createRegisterPendingIntent(packageName, packageCertificate);
 
                 // return PendingIntent to be executed by client
                 Intent result = new Intent();
@@ -107,7 +107,7 @@ public class ApiPermissionHelper {
         } catch (WrongPackageCertificateException e) {
             Log.e(Constants.TAG, "wrong signature!", e);
 
-            PendingIntent pi = piFactory.error(mContext.getString(R.string.api_error_wrong_signature));
+            PendingIntent pi = piFactory.createErrorPendingIntent(mContext.getString(R.string.api_error_wrong_signature));
 
             // return PendingIntent to be executed by client
             Intent result = new Intent();
@@ -158,10 +158,9 @@ public class ApiPermissionHelper {
     }
 
     /**
-     * DEPRECATED API
-     * <p/>
      * Retrieves AccountSettings from database for the application calling this remote service
      */
+    @Deprecated
     protected AccountSettings getAccSettings(String accountName) {
         String currentPkg = getCurrentCallingPackage();
         Log.d(Constants.TAG, "getAccSettings accountName: " + accountName);
@@ -171,16 +170,14 @@ public class ApiPermissionHelper {
         return mProviderHelper.getApiAccountSettings(uri); // can be null!
     }
 
-    /**
-     * @deprecated
-     */
+    @Deprecated
     protected Intent getCreateAccountIntent(Intent data, String accountName) {
         String packageName = getCurrentCallingPackage();
         Log.d(Constants.TAG, "getCreateAccountIntent accountName: " + accountName);
 
         ApiPendingIntentFactory piFactory = new ApiPendingIntentFactory(mContext, data);
 
-        PendingIntent pi = piFactory.createAccount(packageName, accountName);
+        PendingIntent pi = piFactory.createAccountCreationPendingIntent(packageName, accountName);
 
         // return PendingIntent to be executed by client
         Intent result = new Intent();
diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/remote/OpenPgpService.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/remote/OpenPgpService.java
index 7c5351d6a..f898ff2ca 100644
--- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/remote/OpenPgpService.java
+++ b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/remote/OpenPgpService.java
@@ -144,7 +144,7 @@ public class OpenPgpService extends Service {
             // allow the user to verify pub key selection
 
             ApiPendingIntentFactory piFactory = new ApiPendingIntentFactory(getBaseContext(), data);
-            PendingIntent pi = piFactory.selectPublicKey(keyIdsArray, missingEmails,
+            PendingIntent pi = piFactory.createSelectPublicKeyPendingIntent(keyIdsArray, missingEmails,
                     duplicateEmails, noUserIdsCheck);
 
             // return PendingIntent to be executed by client
@@ -459,7 +459,7 @@ public class OpenPgpService extends Service {
                     case OpenPgpSignatureResult.RESULT_KEY_MISSING: {
                         // If signature key is missing we return a PendingIntent to retrieve the key
                         result.putExtra(OpenPgpApi.RESULT_INTENT,
-                                piFactory.importFromKeyserver(signatureResult.getKeyId()));
+                                piFactory.createImportFromKeyserverPendingIntent(signatureResult.getKeyId()));
                         break;
                     }
                     case OpenPgpSignatureResult.RESULT_VALID_CONFIRMED:
@@ -468,7 +468,7 @@ public class OpenPgpService extends Service {
                     case OpenPgpSignatureResult.RESULT_INVALID_KEY_EXPIRED:
                     case OpenPgpSignatureResult.RESULT_INVALID_INSECURE: {
                         // If signature key is known, return PendingIntent to show key
-                        result.putExtra(OpenPgpApi.RESULT_INTENT, piFactory.showKey(signatureResult.getKeyId()));
+                        result.putExtra(OpenPgpApi.RESULT_INTENT, piFactory.createShowKeyPendingIntent(signatureResult.getKeyId()));
                         break;
                     }
                     default:
@@ -542,7 +542,7 @@ public class OpenPgpService extends Service {
                     // allow user to select allowed keys
                     Intent result = new Intent();
                     String packageName = mApiPermissionHelper.getCurrentCallingPackage();
-                    result.putExtra(OpenPgpApi.RESULT_INTENT, piFactory.selectAllowedKeys(packageName));
+                    result.putExtra(OpenPgpApi.RESULT_INTENT, piFactory.createSelectAllowedKeysPendingIntent(packageName));
                     result.putExtra(OpenPgpApi.RESULT_CODE, OpenPgpApi.RESULT_CODE_USER_INTERACTION_REQUIRED);
                     return result;
                 }
@@ -597,14 +597,14 @@ public class OpenPgpService extends Service {
                 }
 
                 // also return PendingIntent that opens the key view activity
-                result.putExtra(OpenPgpApi.RESULT_INTENT, piFactory.showKey(masterKeyId));
+                result.putExtra(OpenPgpApi.RESULT_INTENT, piFactory.createShowKeyPendingIntent(masterKeyId));
 
                 return result;
             } catch (ProviderHelper.NotFoundException e) {
                 // If keys are not in db we return an additional PendingIntent
                 // to retrieve the missing key
                 Intent result = new Intent();
-                result.putExtra(OpenPgpApi.RESULT_INTENT, piFactory.importFromKeyserver(masterKeyId));
+                result.putExtra(OpenPgpApi.RESULT_INTENT, piFactory.createImportFromKeyserverPendingIntent(masterKeyId));
                 result.putExtra(OpenPgpApi.RESULT_CODE, OpenPgpApi.RESULT_CODE_USER_INTERACTION_REQUIRED);
                 return result;
             }
@@ -634,7 +634,7 @@ public class OpenPgpService extends Service {
             String preferredUserId = data.getStringExtra(OpenPgpApi.EXTRA_USER_ID);
 
             ApiPendingIntentFactory piFactory = new ApiPendingIntentFactory(getBaseContext(), data);
-            PendingIntent pi = piFactory.selectSignKeyId(currentPkg, preferredUserId);
+            PendingIntent pi = piFactory.createSelectSignKeyIdPendingIntent(currentPkg, preferredUserId);
 
             // return PendingIntent to be executed by client
             Intent result = new Intent();
@@ -697,7 +697,7 @@ public class OpenPgpService extends Service {
      * - has supported API version
      * - is allowed to call the service (access has been granted)
      *
-     * @return null if everything is okay, or a Bundle with an error/PendingIntent
+     * @return null if everything is okay, or a Bundle with an createErrorPendingIntent/PendingIntent
      */
     private Intent checkRequirements(Intent data) {
         // params Bundle is required!
@@ -760,7 +760,7 @@ public class OpenPgpService extends Service {
         try {
             return executeInternalWithStreams(data, inputStream, outputStream);
         } finally {
-            // always close input and output file descriptors even in error cases
+            // always close input and output file descriptors even in createErrorPendingIntent cases
             if (inputStream != null) {
                 try {
                     inputStream.close();