diff --git a/lucene/core/src/java/org/apache/lucene/util/ByteBlockPool.java b/lucene/core/src/java/org/apache/lucene/util/ByteBlockPool.java
index 37bd1e2ba14..03563e52fb1 100644
--- a/lucene/core/src/java/org/apache/lucene/util/ByteBlockPool.java
+++ b/lucene/core/src/java/org/apache/lucene/util/ByteBlockPool.java
@@ -48,6 +48,8 @@ public final class ByteBlockPool {
   public final static int BYTE_BLOCK_SIZE = 1 << BYTE_BLOCK_SHIFT;
   public final static int BYTE_BLOCK_MASK = BYTE_BLOCK_SIZE - 1;
 
+  /** Abstract class for allocating and freeing byte
+   *  blocks. */
   public abstract static class Allocator {
     protected final int blockSize;
 
@@ -67,6 +69,7 @@ public final class ByteBlockPool {
     }
   }
   
+  /** A simple {@link Allocator} that never recycles. */
   public static final class DirectAllocator extends Allocator {
     
     public DirectAllocator() {
@@ -80,9 +83,10 @@ public final class ByteBlockPool {
     @Override
     public void recycleByteBlocks(byte[][] blocks, int start, int end) {
     }
-    
   }
   
+  /** A simple {@link Allocator} that never recycles, but
+   *  tracks how much total RAM is in use. */
   public static class DirectTrackingAllocator extends Allocator {
     private final Counter bytesUsed;
     
@@ -99,6 +103,7 @@ public final class ByteBlockPool {
       bytesUsed.addAndGet(blockSize);
       return new byte[blockSize];
     }
+
     @Override
     public void recycleByteBlocks(byte[][] blocks, int start, int end) {
       bytesUsed.addAndGet(-((end-start)* blockSize));
@@ -106,7 +111,6 @@ public final class ByteBlockPool {
         blocks[i] = null;
       }
     }
-    
   };
 
 
diff --git a/lucene/core/src/java/org/apache/lucene/util/BytesRefHash.java b/lucene/core/src/java/org/apache/lucene/util/BytesRefHash.java
index 6088605df72..e1c01ee0bd3 100644
--- a/lucene/core/src/java/org/apache/lucene/util/BytesRefHash.java
+++ b/lucene/core/src/java/org/apache/lucene/util/BytesRefHash.java
@@ -500,6 +500,7 @@ public final class BytesRefHash {
     }
   }
 
+  /** Manages allocation of the per-term addresses. */
   public abstract static class BytesStartArray {
     /**
      * Initializes the BytesStartArray. This call will allocate memory
@@ -533,9 +534,9 @@ public final class BytesRefHash {
     public abstract Counter bytesUsed();
   }
   
-  /**
-   * A direct {@link BytesStartArray} that tracks all memory allocation using an {@link Counter} instance.
-   */
+  /** A simple {@link BytesStartArray} that tracks all
+   *  memory allocation using a shared {@link Counter}
+   *  instance.  */
   public static class TrackingDirectBytesStartArray extends BytesStartArray {
     protected final int initSize;
     private int[] bytesStart;
@@ -577,7 +578,14 @@ public final class BytesRefHash {
     }
   }
 
+  /** A simple {@link BytesStartArray} that tracks
+   *  memory allocation using a private {@link AtomicLong}
+   *  instance.  */
   public static class DirectBytesStartArray extends BytesStartArray {
+    // TODO: can't we just merge this w/
+    // TrackingDirectBytesStartArray...?  Just add a ctor
+    // that makes a private bytesUsed?
+
     protected final int initSize;
     private int[] bytesStart;
     private final Counter bytesUsed;
@@ -587,7 +595,6 @@ public final class BytesRefHash {
       this.initSize = initSize;
     }
 
-
     @Override
     public int[] clear() {
       return bytesStart = null;
diff --git a/lucene/core/src/java/org/apache/lucene/util/BytesRefIterator.java b/lucene/core/src/java/org/apache/lucene/util/BytesRefIterator.java
index b22ec1ab758..09c9c482d72 100644
--- a/lucene/core/src/java/org/apache/lucene/util/BytesRefIterator.java
+++ b/lucene/core/src/java/org/apache/lucene/util/BytesRefIterator.java
@@ -21,11 +21,11 @@ import java.io.IOException;
 import java.util.Comparator;
 
 /**
- * A simple iterator interface for {@link BytesRef} iteration
- * 
+ * A simple iterator interface for {@link BytesRef} iteration.
  */
 public interface BytesRefIterator {
-  
+
+  /** Singleton BytesRefIterator that iterates over 0 BytesRefs. */
   public static final BytesRefIterator EMPTY_ITERATOR = new EmptyBytesRefIterator();
   
   /**
@@ -48,7 +48,9 @@ public interface BytesRefIterator {
    * single instance & reuse it.
    */
   public Comparator<BytesRef> getComparator();
-  
+
+  // TODO: private?
+  /** Iterates over 0 BytesRefs. */
   public final static class EmptyBytesRefIterator implements BytesRefIterator {
 
     @Override
@@ -59,7 +61,5 @@ public interface BytesRefIterator {
     public Comparator<BytesRef> getComparator() {
       return null;
     }
-    
   }
-  
 }
diff --git a/lucene/core/src/java/org/apache/lucene/util/DoubleBarrelLRUCache.java b/lucene/core/src/java/org/apache/lucene/util/DoubleBarrelLRUCache.java
index a476bd2b0f8..5648983cd4d 100644
--- a/lucene/core/src/java/org/apache/lucene/util/DoubleBarrelLRUCache.java
+++ b/lucene/core/src/java/org/apache/lucene/util/DoubleBarrelLRUCache.java
@@ -44,6 +44,7 @@ import java.util.Map;
 
 final public class DoubleBarrelLRUCache<K extends DoubleBarrelLRUCache.CloneableKey,V> {
 
+  /** Object providing clone(); the key class must subclass this. */
   public static abstract class CloneableKey {
     @Override
     abstract public Object clone();
diff --git a/lucene/core/src/java/org/apache/lucene/util/OpenBitSetDISI.java b/lucene/core/src/java/org/apache/lucene/util/OpenBitSetDISI.java
index 3e3c77ea823..8de60e263e4 100644
--- a/lucene/core/src/java/org/apache/lucene/util/OpenBitSetDISI.java
+++ b/lucene/core/src/java/org/apache/lucene/util/OpenBitSetDISI.java
@@ -19,7 +19,9 @@ package org.apache.lucene.util;
 
 import java.io.IOException;
 import org.apache.lucene.search.DocIdSetIterator;
- 
+
+/** OpenBitSet with added methods to bulk-update the bits
+ *  from a {@link DocIdSetIterator}. */ 
 public class OpenBitSetDISI extends OpenBitSet {
 
   /** Construct an OpenBitSetDISI with its bits set
diff --git a/lucene/core/src/java/org/apache/lucene/util/PagedBytes.java b/lucene/core/src/java/org/apache/lucene/util/PagedBytes.java
index e9033a3c141..02c0401b7f9 100644
--- a/lucene/core/src/java/org/apache/lucene/util/PagedBytes.java
+++ b/lucene/core/src/java/org/apache/lucene/util/PagedBytes.java
@@ -45,6 +45,10 @@ public final class PagedBytes {
 
   private static final byte[] EMPTY_BYTES = new byte[0];
 
+  /** Provides methods to read BytesRefs from a frozen
+   *  PagedBytes.
+   *
+   * @see #freeze */
   public final static class Reader {
     private final byte[][] blocks;
     private final int[] blockEnds;