diff --git a/hash/sha3/sha3.go b/hash/sha3/sha3.go
index f120ff4..92596a4 100644
--- a/hash/sha3/sha3.go
+++ b/hash/sha3/sha3.go
@@ -49,7 +49,8 @@ type state struct {
 	state     spongeDirection // whether the sponge is absorbing or squeezing
 }
 
-// BlockSize returns the rate of sponge underlying this hash function.
+// BlockSize returns block size in bytes. Corresponds to the input
+// block size B of the HMAC
 func (d *state) BlockSize() int { return d.rate }
 
 // Size returns the output size of the hash function in bytes.
diff --git a/hash/sha3/shake.go b/hash/sha3/shake.go
index ef5fbc7..1742086 100644
--- a/hash/sha3/shake.go
+++ b/hash/sha3/shake.go
@@ -4,9 +4,8 @@
 
 package sha3
 
-// This file defines the ShakeHash interface, and provides
-// functions for creating SHAKE and cSHAKE instances, as well as utility
-// functions for hashing bytes to arbitrary-length output.
+// SHAKE128 and SHAKE256 are FIPS approved XOFs. The cSHAKE128/256
+// are SHAKE-based XOFs supporting domain separation.
 //
 //
 // SHAKE implementation is based on FIPS PUB 202 [1]