diff --git a/src/read.rs b/src/read.rs
index 7bdb9fc6..c619f24c 100644
--- a/src/read.rs
+++ b/src/read.rs
@@ -506,6 +506,12 @@ impl<R: Read + io::Seek> ZipArchive<R> {
     /// The implementation of the cryptographic algorithms has not
     /// gone through a correctness review, and you should assume it is insecure:
     /// passwords used with this API may be compromised.
+    ///
+    /// This function sometimes accepts wrong password. This is because the ZIP spec only allows us
+    /// to check for a 1/256 chance that the password is correct.
+    /// There are many passwords out there that will also pass the validity checks
+    /// we are able to perform. This is a weakness of the ZipCrypto algorithm,
+    /// due to its fairly primitive approach to cryptography.
     pub fn by_name_decrypt<'a>(
         &'a mut self,
         name: &str,
@@ -540,6 +546,12 @@ impl<R: Read + io::Seek> ZipArchive<R> {
     /// The implementation of the cryptographic algorithms has not
     /// gone through a correctness review, and you should assume it is insecure:
     /// passwords used with this API may be compromised.
+    ///
+    /// This function sometimes accepts wrong password. This is because the ZIP spec only allows us
+    /// to check for a 1/256 chance that the password is correct.
+    /// There are many passwords out there that will also pass the validity checks
+    /// we are able to perform. This is a weakness of the ZipCrypto algorithm,
+    /// due to its fairly primitive approach to cryptography.
     pub fn by_index_decrypt<'a>(
         &'a mut self,
         file_number: usize,