diff --git a/storage/key_index.go b/storage/key_index.go
index 2463a9810..5c78bef1b 100644
--- a/storage/key_index.go
+++ b/storage/key_index.go
@@ -44,9 +44,9 @@ var (
 //    {1.0, 2.0, 3.0(t)}
 //
 // Compact a keyIndex removes the versions with smaller or equal to
-// rev except the largest one. If the generations becomes empty
+// rev except the largest one. If the generation becomes empty
 // during compaction, it will be removed. if all the generations get
-// removed, the keyIndex Should be removed.
+// removed, the keyIndex should be removed.
 
 // For example:
 // compact(2) on the previous example
@@ -294,6 +294,7 @@ func (ki *keyIndex) String() string {
 	return s
 }
 
+// generation contains multiple revisions of a key.
 type generation struct {
 	ver     int64
 	created revision // when the generation is created (put in first revision).
diff --git a/storage/revision.go b/storage/revision.go
index d2b0458d5..d31bcbbf2 100644
--- a/storage/revision.go
+++ b/storage/revision.go
@@ -21,9 +21,16 @@ import "encoding/binary"
 // is a '_'. The last 8 bytes is the revision.sub in big-endian format.
 const revBytesLen = 8 + 1 + 8
 
+// A revision indicates modification of the key-value space.
+// The set of changes that share same main revision changes the key-value space atomically.
 type revision struct {
+	// main is the main revision of a set of changes that happen atomically.
 	main int64
-	sub  int64
+
+	// sub is the the sub revision of a change in a set of changes that happen
+	// atomically. Each change has different increasing sub revision in that
+	// set.
+	sub int64
 }
 
 func (a revision) GreaterThan(b revision) bool {