docs: add a note about password handling

src/read.rs

@@ -500,12 +500,18 @@ impl<R: Read + io::Seek> ZipArchive<R> {
     }
 
     /// Search for a file entry by name, decrypt with given password
-    /// 
+    ///
     /// # Warning
-    /// 
+    ///
     /// 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,
@@ -534,12 +540,18 @@ impl<R: Read + io::Seek> ZipArchive<R> {
     }
 
     /// Get a contained file by index, decrypt with given password
-    /// 
+    ///
     /// # Warning
-    /// 
+    ///
     /// 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,