diff --git a/lucene/core/src/java/org/apache/lucene/index/FieldInfo.java b/lucene/core/src/java/org/apache/lucene/index/FieldInfo.java
index 6c2e70fe078..3cba54ea52f 100644
--- a/lucene/core/src/java/org/apache/lucene/index/FieldInfo.java
+++ b/lucene/core/src/java/org/apache/lucene/index/FieldInfo.java
@@ -103,7 +103,7 @@ public final class FieldInfo {
      */
     SORTED,
     /** 
-     * A pre-sorted Set<byte[]>. Fields with this type only store distinct byte values 
+     * A pre-sorted Set&lt;byte[]&gt;. Fields with this type only store distinct byte values 
      * and store additional offset pointers per document to dereference the shared 
      * byte[]s. The stored byte[] is presorted and allows access via document id, 
      * ordinal and by-value.
diff --git a/lucene/core/src/java/org/apache/lucene/index/MultiDocValues.java b/lucene/core/src/java/org/apache/lucene/index/MultiDocValues.java
index 4295054b2e2..8685559a140 100644
--- a/lucene/core/src/java/org/apache/lucene/index/MultiDocValues.java
+++ b/lucene/core/src/java/org/apache/lucene/index/MultiDocValues.java
@@ -269,6 +269,7 @@ public class MultiDocValues {
   
   /** maps per-segment ordinals to/from global ordinal space */
   // TODO: use more efficient packed ints structures?
+  // TODO: pull this out? its pretty generic (maps between N ord()-enabled TermsEnums) 
   public static class OrdinalMap {
     // cache key of whoever asked for this aweful thing
     final Object owner;
@@ -279,6 +280,14 @@ public class MultiDocValues {
     // segmentOrd -> (globalOrd - segmentOrd)
     final AppendingLongBuffer ordDeltas[];
     
+    /** 
+     * Creates an ordinal map that allows mapping ords to/from a merged
+     * space from <code>subs</code>.
+     * @param owner a cache key
+     * @param subs TermsEnums that support {@link TermsEnum#ord()}. They need
+     *             not be dense (e.g. can be FilteredTermsEnums}.
+     * @throws IOException if an I/O error occurred.
+     */
     public OrdinalMap(Object owner, TermsEnum subs[]) throws IOException {
       // create the ordinal mappings by pulling a termsenum over each sub's 
       // unique terms, and walking a multitermsenum over those
@@ -320,18 +329,33 @@ public class MultiDocValues {
       }
     }
     
+    /** 
+     * Given a segment number and segment ordinal, returns
+     * the corresponding global ordinal.
+     */
     public long getGlobalOrd(int subIndex, long segmentOrd) {
       return segmentOrd + ordDeltas[subIndex].get(segmentOrd);
     }
 
+    /**
+     * Given a segment number and global ordinal, returns
+     * the corresponding segment ordinal.
+     */
     public long getSegmentOrd(int subIndex, long globalOrd) {
       return globalOrd - globalOrdDeltas.get(globalOrd);
     }
     
+    /** 
+     * Given a global ordinal, returns the index of the first
+     * sub that contains this term.
+     */
     public int getSegmentNumber(long globalOrd) {
       return (int) subIndexes.get(globalOrd);
     }
     
+    /**
+     * Returns the total number of unique terms in global ord space.
+     */
     public long getValueCount() {
       return globalOrdDeltas.size();
     }
diff --git a/lucene/core/src/java/org/apache/lucene/index/SortedSetDocValues.java b/lucene/core/src/java/org/apache/lucene/index/SortedSetDocValues.java
index 4279b74b28b..ce10caa940a 100644
--- a/lucene/core/src/java/org/apache/lucene/index/SortedSetDocValues.java
+++ b/lucene/core/src/java/org/apache/lucene/index/SortedSetDocValues.java
@@ -33,6 +33,9 @@ public abstract class SortedSetDocValues {
    * constructors, typically implicit.) */
   protected SortedSetDocValues() {}
 
+  /** When returned by {@link #nextOrd()} it means there are no more 
+   * ordinals for the document.
+   */
   public static final long NO_MORE_ORDS = -1;
 
   /**