Fix API docs

1 files changed, 36 insertions, 27 deletions

diff --git a/OpenPGP-Keychain-API/libraries/keychain-api-library/src/org/openintents/openpgp/util/OpenPgpApi.java b/OpenPGP-Keychain-API/libraries/keychain-api-library/src/org/openintents/openpgp/util/OpenPgpApi.java
index 586b091b2..9cf2a5ee9 100644
--- a/OpenPGP-Keychain-API/libraries/keychain-api-library/src/org/openintents/openpgp/util/OpenPgpApi.java
+++ b/OpenPGP-Keychain-API/libraries/keychain-api-library/src/org/openintents/openpgp/util/OpenPgpApi.java
@@ -34,39 +34,40 @@ public class OpenPgpApi {
 
     public static final int API_VERSION = 2;
     public static final String SERVICE_INTENT = "org.openintents.openpgp.IOpenPgpService";
-
-    /**
-     * Sign only
-     *
-     * optional extras:
-     * String       EXTRA_PASSPHRASE  (for key passphrase)
-     */
-    public static final String ACTION_SIGN = "org.openintents.openpgp.action.SIGN";
-
+    
     /**
      * General extras
      * --------------
      *
      * required extras:
-     * int          EXTRA_API_VERSION           (required)
-     * boolean      EXTRA_REQUEST_ASCII_ARMOR   (request ascii armor for ouput)
+     * int           EXTRA_API_VERSION           (always required)
      *
      * returned extras:
-     * int          RESULT_CODE                 (0, 1, or 2 (see OpenPgpApi))
-     * OpenPgpError RESULT_ERROR                (if result_code == 0)
-     * Intent       RESULT_INTENT               (if result_code == 2)
+     * int           RESULT_CODE                 (RESULT_CODE_ERROR, RESULT_CODE_SUCCESS or RESULT_CODE_USER_INTERACTION_REQUIRED)
+     * OpenPgpError  RESULT_ERROR                (if RESULT_CODE == RESULT_CODE_ERROR)
+     * PendingIntent RESULT_INTENT               (if RESULT_CODE == RESULT_CODE_USER_INTERACTION_REQUIRED)
+     */
+
+    /**
+     * Sign only
+     *
+     * optional extras:
+     * boolean       EXTRA_REQUEST_ASCII_ARMOR   (request ascii armor for ouput)
+     * String        EXTRA_PASSPHRASE            (key passphrase)
      */
+    public static final String ACTION_SIGN = "org.openintents.openpgp.action.SIGN";
 
     /**
      * Encrypt
      *
      * required extras:
-     * String[]     EXTRA_USER_IDS    (= emails of recipients) (if more than one key has this user_id, a PendingIntent is returned)
+     * String[]      EXTRA_USER_IDS              (=emails of recipients, if more than one key has a user_id, a PendingIntent is returned via RESULT_INTENT)
      * or
-     * long[]       EXTRA_KEY_IDS
+     * long[]        EXTRA_KEY_IDS
      *
      * optional extras:
-     * String       EXTRA_PASSPHRASE  (for key passphrase)
+     * boolean       EXTRA_REQUEST_ASCII_ARMOR   (request ascii armor for ouput)
+     * String        EXTRA_PASSPHRASE            (key passphrase)
      */
     public static final String ACTION_ENCRYPT = "org.openintents.openpgp.action.ENCRYPT";
 
@@ -74,12 +75,13 @@ public class OpenPgpApi {
      * Sign and encrypt
      *
      * required extras:
-     * String[]     EXTRA_USER_IDS    (= emails of recipients) (if more than one key has this user_id, a PendingIntent is returned)
+     * String[]      EXTRA_USER_IDS              (=emails of recipients, if more than one key has a user_id, a PendingIntent is returned via RESULT_INTENT)
      * or
-     * long[]       EXTRA_KEY_IDS
+     * long[]        EXTRA_KEY_IDS
      *
      * optional extras:
-     * String       EXTRA_PASSPHRASE  (for key passphrase)
+     * boolean       EXTRA_REQUEST_ASCII_ARMOR   (request ascii armor for ouput)
+     * String        EXTRA_PASSPHRASE            (key passphrase)
      */
     public static final String ACTION_SIGN_AND_ENCRYPT = "org.openintents.openpgp.action.SIGN_AND_ENCRYPT";
 
@@ -87,6 +89,12 @@ public class OpenPgpApi {
      * Decrypts and verifies given input stream. This methods handles encrypted-only, signed-and-encrypted,
      * and also signed-only input.
      *
+     * If OpenPgpSignatureResult.getStatus() == OpenPgpSignatureResult.SIGNATURE_UNKNOWN_PUB_KEY
+     * in addition a PendingIntent is returned via RESULT_INTENT to download missing keys.
+     *
+     * optional extras:
+     * boolean       EXTRA_REQUEST_ASCII_ARMOR   (request ascii armor for ouput)
+     *
      * returned extras:
      * OpenPgpSignatureResult   RESULT_SIGNATURE
      */
@@ -96,10 +104,10 @@ public class OpenPgpApi {
      * Get key ids based on given user ids (=emails)
      *
      * required extras:
-     * String[]     EXTRA_USER_IDS
+     * String[]      EXTRA_USER_IDS
      *
      * returned extras:
-     * long[]       EXTRA_KEY_IDS
+     * long[]        EXTRA_KEY_IDS
      */
     public static final String ACTION_GET_KEY_IDS = "org.openintents.openpgp.action.GET_KEY_IDS";
 
@@ -107,11 +115,11 @@ public class OpenPgpApi {
      * Download keys from keyserver
      *
      * required extras:
-     * long[]     EXTRA_KEY_IDS
+     * long[]        EXTRA_KEY_IDS
      */
     public static final String ACTION_DOWNLOAD_KEYS = "org.openintents.openpgp.action.DOWNLOAD_KEYS";
 
-    /* Bundle params */
+    /* Intent extras */
     public static final String EXTRA_API_VERSION = "api_version";
 
     // SIGN, ENCRYPT, SIGN_AND_ENCRYPT, DECRYPT_VERIFY
@@ -122,17 +130,18 @@ public class OpenPgpApi {
     // ENCRYPT, SIGN_AND_ENCRYPT
     public static final String EXTRA_USER_IDS = "user_ids";
     public static final String EXTRA_KEY_IDS = "key_ids";
-    // optional parameter:
+    // optional extras:
     public static final String EXTRA_PASSPHRASE = "passphrase";
 
-    /* Service Bundle returns */
+    /* Service Intent returns */
     public static final String RESULT_CODE = "result_code";
 
     // get actual error object from RESULT_ERROR
     public static final int RESULT_CODE_ERROR = 0;
     // success!
     public static final int RESULT_CODE_SUCCESS = 1;
-    // executeServiceMethod intent and do it again with intent
+    // get PendingIntent from RESULT_INTENT, start PendingIntent with startIntentSenderForResult,
+    // and execute service method again in onActivityResult
     public static final int RESULT_CODE_USER_INTERACTION_REQUIRED = 2;
 
     public static final String RESULT_ERROR = "error";