documentation and cleanup

3 files changed, 24 insertions, 4 deletions

diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/CharsetVerifier.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/CharsetVerifier.java
index 5d63ced22..c563beeac 100644
--- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/CharsetVerifier.java
+++ b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/CharsetVerifier.java
@@ -12,7 +12,14 @@ import android.content.ClipDescription;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 
-
+/** This class can be used to guess whether a stream of data is encoded in a given
+ * charset or not.
+ *
+ * An object of this class must be initialized with a byte[] buffer, which should
+ * be filled with data, then processed with {@link #readBytesFromBuffer}. This can
+ * be done any number of times. Once all data has been read, a final status can be
+ * read using the getter methods.
+ */
 public class CharsetVerifier {
 
     private final ByteBuffer bufWrap;
@@ -58,7 +65,7 @@ public class CharsetVerifier {
         charsetDecoder.reset();
     }
 
-    public void write(int pos, int len) {
+    public void readBytesFromBuffer(int pos, int len) {
         if (isFinished) {
             throw new IllegalStateException("cannot write again after reading charset status!");
         }
@@ -111,12 +118,25 @@ public class CharsetVerifier {
         return charset;
     }
 
+    /** Returns true if the data which was read is definitely binary.
+     *
+     * This can happen when either the supplied mimeType indicated a non-ambiguous
+     * binary data type, or if we guessed a charset but got errors while decoding.
+     */
     public boolean isDefinitelyBinary() {
         finishIfNecessary();
         return !isTextMimeType && (!isPossibleTextMimeType || (isGuessed && isFaulty));
     }
 
+    /** Returns true iff the data which was read is probably (or
+     * definitely) text.
+     *
+     * The corner case where isDefinitelyBinary returns false but isProbablyText
+     * returns true is where the charset was provided by the data (so is not
+     * guessed) but is still faulty.
+     */
     public boolean isProbablyText() {
+        finishIfNecessary();
         return isTextMimeType || isPossibleTextMimeType && (!isGuessed || !isFaulty);
     }
 }
diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/InputDataOperation.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/InputDataOperation.java
index ff9377581..74d94d83e 100644
--- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/InputDataOperation.java
+++ b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/InputDataOperation.java
@@ -335,7 +335,7 @@ public class InputDataOperation extends BaseOperation<InputDataParcel> {
                 do {
                     totalLength += len;
                     out.write(buf, 0, len);
-                    charsetVerifier.write(0, len);
+                    charsetVerifier.readBytesFromBuffer(0, len);
                 } while ((len = is.read(buf)) > 0);
 
                 log.add(LogType.MSG_DATA_MIME_LENGTH, 3, Long.toString(totalLength));
diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/PgpDecryptVerifyOperation.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/PgpDecryptVerifyOperation.java
index feff78726..90c1b1242 100644
--- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/PgpDecryptVerifyOperation.java
+++ b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/PgpDecryptVerifyOperation.java
@@ -449,7 +449,7 @@ public class PgpDecryptVerifyOperation extends BaseOperation<PgpDecryptVerifyInp
             // update signature buffer if signature is also present
             signatureChecker.updateSignatureData(buffer, 0, length);
 
-            charsetVerifier.write(0, length);
+            charsetVerifier.readBytesFromBuffer(0, length);
 
             // note down first couple of bytes for "magic bytes" file type detection
             if (alreadyWritten == 0) {