keccak: 2018 edition upgrade, lints, docs (#32)

- Bumps the crate's edition to 2018, which is MSRV-compatible.
- Adds a more expansive set of lints
- Adds the `missing_docs` lint, and adds docs where missing
- Fixes tests on ARMv8

keccak/Cargo.toml

@@ -12,6 +12,7 @@ repository = "https://github.com/RustCrypto/sponges/tree/master/keccak"
 keywords = ["crypto", "sponge", "keccak", "keccak-f", "keccak-p"]
 categories = ["cryptography", "no-std"]
 readme = "README.md"
+edition = "2018"
 
 [features]
 asm = []       # Use optimized assembly when available (currently only ARMv8)

keccak/src/armv8.rs

@@ -185,9 +185,9 @@ mod tests {
         ];
 
         let mut state = [0u64; 25];
-        unsafe { keccak_f1600(&mut state) };
+        unsafe { f1600_armv8_sha3_asm(&mut state) };
         assert_eq!(state, state_first);
-        unsafe { keccak_f1600(&mut state) };
+        unsafe { f1600_armv8_sha3_asm(&mut state) };
         assert_eq!(state, state_second);
     }
 }

keccak/src/lib.rs

@@ -35,9 +35,23 @@
 //!
 //! [1]: https://docs.rs/sha3
 //! [2]: https://docs.rs/tiny-keccak
+
 #![no_std]
-#![allow(non_upper_case_globals)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![cfg_attr(feature = "simd", feature(portable_simd))]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",
+    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg"
+)]
+#![allow(non_upper_case_globals)]
+#![warn(
+    clippy::mod_module_files,
+    clippy::unwrap_used,
+    missing_docs,
+    rust_2018_idioms,
+    unused_lifetimes,
+    unused_qualifications
+)]
 
 use core::{
     convert::TryInto,
@@ -92,6 +106,8 @@ const RC: [u64; 24] = [
     0x8000000080008008,
 ];
 
+/// Keccak is a permutation over an array of lanes which comprise the sponge
+/// construction.
 pub trait LaneSize:
     Copy
     + Clone
@@ -104,9 +120,13 @@ pub trait LaneSize:
     + BitXor<Output = Self>
     + Not<Output = Self>
 {
+    /// Number of rounds of the Keccak-f permutation.
     const KECCAK_F_ROUND_COUNT: usize;
 
+    /// Truncate function.
     fn truncate_rc(rc: u64) -> Self;
+
+    /// Rotate left function.
     fn rotate_left(self, n: u32) -> Self;
 }
 
@@ -129,10 +149,12 @@ macro_rules! impl_lanesize {
 impl_lanesize!(u8, 18, |rc: u64| { rc.to_le_bytes()[0] });
 impl_lanesize!(u16, 20, |rc: u64| {
     let tmp = rc.to_le_bytes();
+    #[allow(clippy::unwrap_used)]
     Self::from_le_bytes(tmp[..size_of::<Self>()].try_into().unwrap())
 });
 impl_lanesize!(u32, 22, |rc: u64| {
     let tmp = rc.to_le_bytes();
+    #[allow(clippy::unwrap_used)]
     Self::from_le_bytes(tmp[..size_of::<Self>()].try_into().unwrap())
 });
 impl_lanesize!(u64, 24, |rc: u64| { rc });
@@ -153,6 +175,7 @@ impl_keccak!(f800, u32);
 #[cfg(not(all(target_arch = "aarch64", feature = "asm")))]
 impl_keccak!(f1600, u64);
 
+/// Keccak-f[1600] permutation.
 #[cfg(all(target_arch = "aarch64", feature = "asm"))]
 pub fn f1600(state: &mut [u64; PLEN]) {
     if armv8_sha3_intrinsics::get() {
@@ -165,8 +188,8 @@ pub fn f1600(state: &mut [u64; PLEN]) {
 #[cfg(feature = "simd")]
 /// SIMD implementations for Keccak-f1600 sponge function
 pub mod simd {
+    use crate::{keccak_p, LaneSize, PLEN};
     pub use core::simd::{u64x2, u64x4, u64x8};
-    use {keccak_p, LaneSize, PLEN};
 
     macro_rules! impl_lanesize_simd_u64xn {
         ($type:ty) => {
@@ -254,7 +277,7 @@ pub fn keccak_p<L: LaneSize>(state: &mut [L; PLEN], round_count: usize) {
 
 #[cfg(test)]
 mod tests {
-    use {keccak_p, LaneSize, PLEN};
+    use crate::{keccak_p, LaneSize, PLEN};
 
     fn keccak_f<L: LaneSize>(state_first: [L; PLEN], state_second: [L; PLEN]) {
         let mut state = [L::default(); PLEN];
@@ -384,8 +407,8 @@ mod tests {
 
     #[cfg(feature = "simd")]
     mod simd {
-        use simd::{u64x2, u64x4, u64x8};
-        use tests::keccak_f;
+        use super::keccak_f;
+        use core::simd::{u64x2, u64x4, u64x8};
 
         macro_rules! impl_keccak_f1600xn {
             ($name:ident, $type:ty) => {

keccak/src/unroll.rs

@@ -1,3 +1,4 @@
+/// unroll5
 #[cfg(not(feature = "no_unroll"))]
 #[macro_export]
 macro_rules! unroll5 {
@@ -10,6 +11,7 @@ macro_rules! unroll5 {
     };
 }
 
+/// unroll5
 #[cfg(feature = "no_unroll")]
 #[macro_export]
 macro_rules! unroll5 {
@@ -18,6 +20,7 @@ macro_rules! unroll5 {
     }
 }
 
+/// unroll24
 #[cfg(not(feature = "no_unroll"))]
 #[macro_export]
 macro_rules! unroll24 {
@@ -49,6 +52,7 @@ macro_rules! unroll24 {
     };
 }
 
+/// unroll24
 #[cfg(feature = "no_unroll")]
 #[macro_export]
 macro_rules! unroll24 {