From 168432abab88d6572da0057b9de637c6eeeb3523 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dominik=20Sch=C3=BCrmann?= <dominik@dominikschuermann.de>
Date: Mon, 16 Sep 2013 16:08:44 +0200
Subject: [PATCH] API documentation

---
 OpenPGP-Keychain/AndroidManifest.xml            |  2 +-
 .../openintents/openpgp/IOpenPgpCallback.aidl   | 16 ++++++++++++++--
 .../openintents/openpgp/IOpenPgpService.aidl    | 17 +++++++++++++----
 .../openpgp/OpenPgpSignatureResult.java         |  4 ++++
 .../keychain/service/remote/OpenPgpService.java |  2 +-
 5 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/OpenPGP-Keychain/AndroidManifest.xml b/OpenPGP-Keychain/AndroidManifest.xml
index b9410030e..fdaf3b3e3 100644
--- a/OpenPGP-Keychain/AndroidManifest.xml
+++ b/OpenPGP-Keychain/AndroidManifest.xml
@@ -18,7 +18,7 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="org.sufficientlysecure.keychain"
     android:installLocation="auto"
-    android:versionCode="21100"
+    android:versionCode="21101"
     android:versionName="2.1.1" >
 
     <!--
diff --git a/OpenPGP-Keychain/src/org/openintents/openpgp/IOpenPgpCallback.aidl b/OpenPGP-Keychain/src/org/openintents/openpgp/IOpenPgpCallback.aidl
index e0ac43d22..68773afb9 100644
--- a/OpenPGP-Keychain/src/org/openintents/openpgp/IOpenPgpCallback.aidl
+++ b/OpenPGP-Keychain/src/org/openintents/openpgp/IOpenPgpCallback.aidl
@@ -22,10 +22,22 @@ import org.openintents.openpgp.OpenPgpError;
 interface IOpenPgpCallback {
     
     /**
-     * CryptoSignatureResult is only returned if the Callback was used from decryptAndVerify
-     *
+     * onSuccess returns on successful OpenPGP operations.
+     * 
+     * @param outputBytes
+     *            contains resulting output bytes (decrypted content/content without signature)
+     * @param signatureResult
+     *            signatureResult is only non-null if decryptAndVerify() was called and the content
+     *            was encrypted or signed-and-encrypted.
      */
     oneway void onSuccess(in byte[] outputBytes, in OpenPgpSignatureResult signatureResult);
 
+    /**
+     * onError returns on errors or when allowUserInteraction was set to false, but user interaction
+     * was required execute an OpenPGP operation.
+     * 
+     * @param error
+     *            See OpenPgpError class for more information.
+     */
     oneway void onError(in OpenPgpError error);
 }
\ No newline at end of file
diff --git a/OpenPGP-Keychain/src/org/openintents/openpgp/IOpenPgpService.aidl b/OpenPGP-Keychain/src/org/openintents/openpgp/IOpenPgpService.aidl
index ca291469c..87e2df537 100644
--- a/OpenPGP-Keychain/src/org/openintents/openpgp/IOpenPgpService.aidl
+++ b/OpenPGP-Keychain/src/org/openintents/openpgp/IOpenPgpService.aidl
@@ -27,6 +27,8 @@ interface IOpenPgpService {
     /**
      * Encrypt
      * 
+     * After successful encryption, callback's onSuccess will contain the resulting output bytes.
+     * 
      * @param inputBytes
      *            Byte array you want to encrypt
      * @param encryptionUserIds
@@ -43,9 +45,11 @@ interface IOpenPgpService {
     
     /**
      * Sign
+     * 
+     * After successful signing, callback's onSuccess will contain the resulting output bytes.
      *
      * @param inputBytes
-     *            Byte array you want to encrypt
+     *            Byte array you want to sign
      * @param asciiArmor
      *            Encode for ASCII (Radix-64, 33 percent overhead compared to binary)
      * @param allowUserInteraction
@@ -58,9 +62,11 @@ interface IOpenPgpService {
     
     /**
      * Sign then encrypt
+     * 
+     * After successful signing and encryption, callback's onSuccess will contain the resulting output bytes.
      *
      * @param inputBytes
-     *            Byte array you want to encrypt
+     *            Byte array you want to sign and encrypt
      * @param encryptionUserIds
      *            User Ids (emails) of recipients
      * @param signatureUserId
@@ -76,8 +82,11 @@ interface IOpenPgpService {
             in boolean asciiArmor, in boolean allowUserInteraction, in IOpenPgpCallback callback);
     
     /**
-     * Decrypts and verifies given input bytes. If no signature is present this method
-     * will only decrypt.
+     * Decrypts and verifies given input bytes. This methods handles the encrypted-only, signed-and-encrypted,
+     * and also signed-only inputBytes.
+     * 
+     * After successful decryption, callback's onSuccess will contain the resulting output bytes.
+     * callback's onSuccess will return the signatureResult for signed-and-encrypted and signed-only inputs.
      * 
      * @param inputBytes
      *            Byte array you want to decrypt and verify
diff --git a/OpenPGP-Keychain/src/org/openintents/openpgp/OpenPgpSignatureResult.java b/OpenPGP-Keychain/src/org/openintents/openpgp/OpenPgpSignatureResult.java
index 0d24e7bd4..6ace29385 100644
--- a/OpenPGP-Keychain/src/org/openintents/openpgp/OpenPgpSignatureResult.java
+++ b/OpenPGP-Keychain/src/org/openintents/openpgp/OpenPgpSignatureResult.java
@@ -20,9 +20,13 @@ import android.os.Parcel;
 import android.os.Parcelable;
 
 public class OpenPgpSignatureResult implements Parcelable {
+    // generic error on signature verification
     public static final int SIGNATURE_ERROR = 0;
+    // successfully verified signature, with trusted public key
     public static final int SIGNATURE_SUCCESS_TRUSTED = 1;
+    // no public key was found for this signature verification
     public static final int SIGNATURE_UNKNOWN = 2;
+    // successfully verified signature, but with untrusted public key
     public static final int SIGNATURE_SUCCESS_UNTRUSTED = 3;
 
     int signatureStatus;
diff --git a/OpenPGP-Keychain/src/org/sufficientlysecure/keychain/service/remote/OpenPgpService.java b/OpenPGP-Keychain/src/org/sufficientlysecure/keychain/service/remote/OpenPgpService.java
index a6fb78f71..71b502fba 100644
--- a/OpenPGP-Keychain/src/org/sufficientlysecure/keychain/service/remote/OpenPgpService.java
+++ b/OpenPGP-Keychain/src/org/sufficientlysecure/keychain/service/remote/OpenPgpService.java
@@ -62,7 +62,7 @@ public class OpenPgpService extends RemoteService {
         if (passphrase == null) {
             if (!allowUserInteraction) {
                 throw new UserInteractionRequiredException(
-                        "Passphrase not found in cache! User interaction required!");
+                        "Passphrase not found in cache, please enter your passphrase!");
             }
 
             Log.d(Constants.TAG, "No passphrase! Activity required!");