diff --git a/lucene/core/src/java/org/apache/lucene/document/Field.java b/lucene/core/src/java/org/apache/lucene/document/Field.java
index 07e31e9..67294e9 100644
--- a/lucene/core/src/java/org/apache/lucene/document/Field.java
+++ b/lucene/core/src/java/org/apache/lucene/document/Field.java
@@ -554,7 +554,7 @@
       return analyzer.tokenStream(name(), stringValue());
     }
 
-    throw new IllegalArgumentException("Field must have either TokenStream, String, Reader or Number value; this=" + this);
+    throw new IllegalArgumentException("Field must have either TokenStream, String, Reader or Number value; got " + this);
   }
   
   static final class StringTokenStream extends TokenStream {
diff --git a/lucene/facet/build.xml b/lucene/facet/build.xml
index d6ed7de..c7dcdcd 100644
--- a/lucene/facet/build.xml
+++ b/lucene/facet/build.xml
@@ -24,7 +24,7 @@
   </description>
 
   <property name="forbidden-sysout-excludes" value="
-    org/apache/lucene/facet/util/PrintTaxonomyStats.class
+    org/apache/lucene/facet/taxonomy/PrintTaxonomyStats.class
   "/>
 
   <import file="../module-build.xml"/>
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java b/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java
index dc3ca6d..03c1da4 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java
@@ -59,6 +59,7 @@
 
   private final Map<Object,CachedOrds> ordsCache = new WeakHashMap<Object,CachedOrds>();
 
+  /** Sole constructor. */
   public CachedOrdinalsReader(OrdinalsReader source) {
     this.source = source;
   }
@@ -94,8 +95,11 @@
 
   /** Holds the cached ordinals in two paralel {@code int[]} arrays. */
   public static final class CachedOrds {
-    
+
+    /** Index into {@link #ordinals} for each document. */
     public final int[] offsets;
+
+    /** Holds ords for all docs. */
     public final int[] ordinals;
 
     /**
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/DocValuesOrdinalsReader.java b/lucene/facet/src/java/org/apache/lucene/facet/DocValuesOrdinalsReader.java
index 0f91f3b..ab257ae 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/DocValuesOrdinalsReader.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/DocValuesOrdinalsReader.java
@@ -30,10 +30,12 @@
 public class DocValuesOrdinalsReader extends OrdinalsReader {
   private final String field;
 
+  /** Default constructor. */
   public DocValuesOrdinalsReader() {
     this(FacetsConfig.DEFAULT_INDEX_FIELD_NAME);
   }
 
+  /** Create this, with the specified indexed field name. */
   public DocValuesOrdinalsReader(String field) {
     this.field = field;
   }
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java b/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java
index 92c5229..4e7296e 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java
@@ -66,9 +66,17 @@
  */
 public class DrillSideways {
 
+  /** {@link IndexSearcher} passed to constructor. */
   protected final IndexSearcher searcher;
+
+  /** {@link TaxonomyReader} passed to constructor. */
   protected final TaxonomyReader taxoReader;
+
+  /** {@link SortedSetDocValuesReaderState} passed to
+   *  constructor; can be null. */
   protected final SortedSetDocValuesReaderState state;
+
+  /** {@link FacetsConfig} passed to constructor. */
   protected final FacetsConfig config;
 
   /** Create a new {@code DrillSideways} instance. */
@@ -371,6 +379,8 @@
     return false;
   }
 
+  /** Result of a drill sideways search, including the
+   *  {@link Facets} and {@link TopDocs}. */
   public static class DrillSidewaysResult {
     /** Combined drill down & sideways results. */
     public final Facets facets;
@@ -378,6 +388,7 @@
     /** Hits. */
     public final TopDocs hits;
 
+    /** Sole constructor. */
     public DrillSidewaysResult(Facets facets, TopDocs hits) {
       this.facets = facets;
       this.hits = hits;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java b/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java
index 9c35b1e..b90622d 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java
@@ -19,6 +19,7 @@
 
 import java.util.Arrays;
 
+/** Counts or aggregates for a single dimension. */
 public final class FacetResult {
 
   /** Dimension that was requested. */
@@ -38,6 +39,7 @@
   /** Child counts. */
   public final LabelAndValue[] labelValues;
 
+  /** Sole constructor. */
   public FacetResult(String dim, String[] path, Number value, LabelAndValue[] labelValues, int childCount) {
     this.dim = dim;
     this.path = path;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/Facets.java b/lucene/facet/src/java/org/apache/lucene/facet/Facets.java
index b63a7c5..4842603 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/Facets.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/Facets.java
@@ -25,6 +25,10 @@
  *  @lucene.experimental */
 public abstract class Facets {
 
+  /** Default constructor. */
+  public Facets() {
+  }
+
   /** Returns the topN child labels under the specified
    *  path.  Returns null if the specified path doesn't
    *  exist or if this dimension was never seen. */
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/FacetsCollector.java b/lucene/facet/src/java/org/apache/lucene/facet/FacetsCollector.java
index 33fd31d..4f52d57 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/FacetsCollector.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/FacetsCollector.java
@@ -62,11 +62,19 @@
    */
   public final static class MatchingDocs {
     
+    /** Context for this segment. */
     public final AtomicReaderContext context;
+
+    /** Which documents were seen. */
     public final FixedBitSet bits;
+
+    /** Non-sparse scores array. */
     public final float[] scores;
-    public final int totalHits;
     
+    /** Total number of hits */
+    public final int totalHits;
+
+    /** Sole constructor. */
     public MatchingDocs(AtomicReaderContext context, FixedBitSet bits, int totalHits, float[] scores) {
       this.context = context;
       this.bits = bits;
@@ -75,14 +83,18 @@
     }
   }
 
+  /** Default constructor */
   public FacetsCollector() {
     this(false);
   }
 
+  /** Create this; if {@code keepScores} is true then a
+   *  float[] is allocated to hold score of all hits. */
   public FacetsCollector(boolean keepScores) {
     this.keepScores = keepScores;
   }
 
+  /** True if scores were saved. */
   public boolean getKeepScores() {
     return keepScores;
   }
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java b/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java
index 1152a57..a2dc94e 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java
@@ -59,6 +59,8 @@
  *  @lucene.experimental */
 public class FacetsConfig {
 
+  /** Which Lucene field holds the drill-downs and ords (as
+   *  doc values). */
   public static final String DEFAULT_INDEX_FIELD_NAME = "$facets";
 
   private final Map<String,DimConfig> fieldTypes = new ConcurrentHashMap<String,DimConfig>();
@@ -84,6 +86,10 @@
     /** Actual field where this dimension's facet labels
      *  should be indexed */
     public String indexFieldName = DEFAULT_INDEX_FIELD_NAME;
+
+    /** Default constructor. */
+    public DimConfig() {
+    }
   }
 
   /** Default per-dimension configuration. */
@@ -148,6 +154,7 @@
     ft.indexFieldName = indexFieldName;
   }
 
+  /** Returns map of field name to {@link DimConfig}. */
   public Map<String,DimConfig> getDimConfigs() {
     return fieldTypes;
   }
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java b/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java
index 88b871a..018d6a6 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java
@@ -17,6 +17,8 @@
  * limitations under the License.
  */
 
+/** Single label and its value, usually contained in a
+ *  {@link FacetResult}. */
 public final class LabelAndValue {
   /** Facet's label. */
   public final String label;
@@ -24,6 +26,7 @@
   /** Value associated with this label. */
   public final Number value;
 
+  /** Sole constructor. */
   public LabelAndValue(String label, Number value) {
     this.label = label;
     this.value = value;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/MultiFacets.java b/lucene/facet/src/java/org/apache/lucene/facet/MultiFacets.java
index 3558776..00cead2 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/MultiFacets.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/MultiFacets.java
@@ -27,10 +27,13 @@
   private final Map<String,Facets> dimToFacets;
   private final Facets defaultFacets;
 
+  /** Create this, with no default {@link Facets}. */
   public MultiFacets(Map<String,Facets> dimToFacets) {
     this(dimToFacets, null);
   }
 
+  /** Create this, with the specified default {@link Facets}
+   *  for fields not included in {@code dimToFacets}. */
   public MultiFacets(Map<String,Facets> dimToFacets, Facets defaultFacets) {
     this.dimToFacets = dimToFacets;
     this.defaultFacets = defaultFacets;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/OrdinalsReader.java b/lucene/facet/src/java/org/apache/lucene/facet/OrdinalsReader.java
index 666fd70..8a3224e 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/OrdinalsReader.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/OrdinalsReader.java
@@ -26,14 +26,25 @@
 
 public abstract class OrdinalsReader {
 
+  /** Returns ordinals for documents in one segment. */
   public static abstract class OrdinalsSegmentReader {
     /** Get the ordinals for this document.  ordinals.offset
      *  must always be 0! */
     public abstract void get(int doc, IntsRef ordinals) throws IOException;
+
+    /** Default constructor. */
+    public OrdinalsSegmentReader() {
+    }
+  }
+
+  /** Default constructor. */
+  public OrdinalsReader() {
   }
 
   /** Set current atomic reader. */
   public abstract OrdinalsSegmentReader getReader(AtomicReaderContext context) throws IOException;
 
+  /** Returns the indexed field name this {@code
+   *  OrdinalsReader} is reading from. */
   public abstract String getIndexFieldName();
 }
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndFloatQueue.java b/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndFloatQueue.java
index 91d9e6d9..e6972d4 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndFloatQueue.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndFloatQueue.java
@@ -23,11 +23,21 @@
  *  then tie break by smallest ord. */
 public class TopOrdAndFloatQueue extends PriorityQueue<TopOrdAndFloatQueue.OrdAndValue> {
 
+  /** Holds a single entry. */
   public static final class OrdAndValue {
+
+    /** Ordinal of the entry. */
     public int ord;
+
+    /** Value associated with the ordinal. */
     public float value;
+
+    /** Default constructor. */
+    public OrdAndValue() {
+    }
   }
 
+  /** Sole constructor. */
   public TopOrdAndFloatQueue(int topN) {
     super(topN, false);
   }
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndIntQueue.java b/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndIntQueue.java
index 06fffb7..b605441 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndIntQueue.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndIntQueue.java
@@ -23,11 +23,21 @@
  *  then tie break by smallest ord. */
 public class TopOrdAndIntQueue extends PriorityQueue<TopOrdAndIntQueue.OrdAndValue> {
 
+  /** Holds a single entry. */
   public static final class OrdAndValue {
+
+    /** Ordinal of the entry. */
     public int ord;
+
+    /** Value associated with the ordinal. */
     public int value;
+
+    /** Default constructor. */
+    public OrdAndValue() {
+    }
   }
 
+  /** Sole constructor. */
   public TopOrdAndIntQueue(int topN) {
     super(topN, false);
   }
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/range/DoubleRange.java b/lucene/facet/src/java/org/apache/lucene/facet/range/DoubleRange.java
index 55f5747..21423cf 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/range/DoubleRange.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/range/DoubleRange.java
@@ -26,7 +26,7 @@
 import org.apache.lucene.search.DocIdSet;
 import org.apache.lucene.search.DocIdSetIterator;
 import org.apache.lucene.search.Filter;
-import org.apache.lucene.search.NumericRangeFilter;
+import org.apache.lucene.search.NumericRangeFilter; // javadocs
 import org.apache.lucene.util.Bits;
 import org.apache.lucene.util.NumericUtils;
 
@@ -35,9 +35,16 @@
   final double minIncl;
   final double maxIncl;
 
+  /** Minimum. */
   public final double min;
+
+  /** Maximum. */
   public final double max;
+
+  /** True if the minimum value is inclusive. */
   public final boolean minInclusive;
+
+  /** True if the maximum value is inclusive. */
   public final boolean maxInclusive;
 
   /** Create a DoubleRange. */
@@ -76,6 +83,7 @@
     this.maxIncl = maxIn;
   }
 
+  /** True if this range accepts the provided value. */
   public boolean accept(double value) {
     return value >= minIncl && value <= maxIncl;
   }
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/range/LongRange.java b/lucene/facet/src/java/org/apache/lucene/facet/range/LongRange.java
index 209d780..e2ee915 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/range/LongRange.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/range/LongRange.java
@@ -26,7 +26,7 @@
 import org.apache.lucene.search.DocIdSet;
 import org.apache.lucene.search.DocIdSetIterator;
 import org.apache.lucene.search.Filter;
-import org.apache.lucene.search.NumericRangeFilter;
+import org.apache.lucene.search.NumericRangeFilter; // javadocs
 import org.apache.lucene.util.Bits;
 
 /** Represents a range over long values. */
@@ -34,9 +34,16 @@
   final long minIncl;
   final long maxIncl;
 
+  /** Minimum. */
   public final long min;
+
+  /** Maximum. */
   public final long max;
+
+  /** True if the minimum value is inclusive. */
   public final boolean minInclusive;
+
+  /** True if the maximum value is inclusive. */
   public final boolean maxInclusive;
 
   // TODO: can we require fewer args? (same for
@@ -74,6 +81,7 @@
     this.maxIncl = maxIn;
   }
 
+  /** True if this range accepts the provided value. */
   public boolean accept(long value) {
     return value >= minIncl && value <= maxIncl;
   }
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/range/Range.java b/lucene/facet/src/java/org/apache/lucene/facet/range/Range.java
index 2e191aa..b003b7f 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/range/Range.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/range/Range.java
@@ -21,8 +21,11 @@
  *
  *  @lucene.experimental */
 public abstract class Range {
+
+  /** Label that identifies this range. */
   public final String label;
 
+  /** Sole constructor. */
   protected Range(String label) {
     if (label == null) {
       throw new NullPointerException("label cannot be null");
@@ -30,6 +33,7 @@
     this.label = label;
   }
 
+  /** Invoke this for a useless range. */
   protected void failNoMatch() {
     throw new IllegalArgumentException("range \"" + label + "\" matches nothing");
   }
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/range/RangeFacetCounts.java b/lucene/facet/src/java/org/apache/lucene/facet/range/RangeFacetCounts.java
index 39257a7..cd5c541 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/range/RangeFacetCounts.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/range/RangeFacetCounts.java
@@ -30,9 +30,16 @@
  *
  *  @lucene.experimental */
 abstract class RangeFacetCounts extends Facets {
+  /** Ranges passed to constructor. */
   protected final Range[] ranges;
+
+  /** Counts, initialized in by subclass. */
   protected final int[] counts;
+
+  /** Our field name. */
   protected final String field;
+
+  /** Total number of hits. */
   protected int totCount;
 
   /** Create {@code RangeFacetCounts}, using {@link
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetCounts.java b/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetCounts.java
index 7491817..a8fcfc6 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetCounts.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetCounts.java
@@ -54,7 +54,7 @@
  *  then used from a single thread, because it holds a
  *  thread-private instance of {@link SortedSetDocValues}.
  * 
- * <p><b>NOTE:<b/>: tie-break is by unicode sort order
+ * <p><b>NOTE:</b>: tie-break is by unicode sort order
  *
  * @lucene.experimental */
 public class SortedSetDocValuesFacetCounts extends Facets {
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetField.java b/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetField.java
index 9bdf243..33e5381 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetField.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetField.java
@@ -30,10 +30,14 @@
     TYPE.setIndexed(true);
     TYPE.freeze();
   }
-  
+
+  /** Dimension. */
   public final String dim;
+
+  /** Label. */
   public final String label;
 
+  /** Sole constructor. */
   public SortedSetDocValuesFacetField(String dim, String label) {
     super("dummy", TYPE);
     this.dim = dim;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesReaderState.java b/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesReaderState.java
index 442d778..2518e6c 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesReaderState.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesReaderState.java
@@ -50,6 +50,8 @@
   private final String field;
   private final AtomicReader topReader;
   private final int valueCount;
+
+  /** {@link IndexReader} passed to the constructor. */
   public final IndexReader origReader;
 
   /** Holds start/end range of ords, which maps to one
@@ -126,22 +128,27 @@
     }
   }
 
+  /** Return top-level doc values. */
   public SortedSetDocValues getDocValues() throws IOException {
     return topReader.getSortedSetDocValues(field);
   }
 
+  /** Returns mapping from prefix to {@link OrdRange}. */
   public Map<String,OrdRange> getPrefixToOrdRange() {
     return prefixToOrdRange;
   }
 
+  /** Returns the {@link OrdRange} for this dimension. */
   public OrdRange getOrdRange(String dim) {
     return prefixToOrdRange.get(dim);
   }
 
+  /** Indexed field we are reading. */
   public String getField() {
     return field;
   }
 
+  /** Number of unique labels. */
   public int getSize() {
     return valueCount;
   }
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/AssociationFacetField.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/AssociationFacetField.java
index b217c36..b03591d 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/AssociationFacetField.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/AssociationFacetField.java
@@ -43,8 +43,13 @@
     TYPE.freeze();
   }
   
+  /** Dimension for this field. */
   public final String dim;
+
+  /** Facet path for this field. */
   public final String[] path;
+
+  /** Associated value. */
   public final BytesRef assoc;
 
   /** Creates this from {@code dim} and {@code path} and an
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FacetLabel.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FacetLabel.java
index 94a5df6..ee14e7f 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FacetLabel.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FacetLabel.java
@@ -21,8 +21,8 @@
 
 import java.util.Arrays;
 
-import org.apache.lucene.facet.taxonomy.writercache.LruTaxonomyWriterCache;
-import org.apache.lucene.facet.taxonomy.writercache.NameHashIntCacheLRU;
+import org.apache.lucene.facet.taxonomy.writercache.LruTaxonomyWriterCache; // javadocs
+import org.apache.lucene.facet.taxonomy.writercache.NameHashIntCacheLRU; // javadocs
 
 /**
  * Holds a sequence of string components, specifying the hierarchical name of a
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FloatTaxonomyFacets.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FloatTaxonomyFacets.java
index db4413c..d82db6e 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FloatTaxonomyFacets.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FloatTaxonomyFacets.java
@@ -30,13 +30,16 @@
  *  to a per-ords float[]. */
 public abstract class FloatTaxonomyFacets extends TaxonomyFacets {
 
+  /** Per-ordinal value. */
   protected final float[] values;
 
+  /** Sole constructor. */
   protected FloatTaxonomyFacets(String indexFieldName, TaxonomyReader taxoReader, FacetsConfig config) throws IOException {
     super(indexFieldName, taxoReader, config);
     values = new float[taxoReader.getSize()];
   }
   
+  /** Rolls up any single-valued hierarchical dimensions. */
   protected void rollup() throws IOException {
     // Rollup any necessary dims:
     for(Map.Entry<String,DimConfig> ent : config.getDimConfigs().entrySet()) {
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/IntTaxonomyFacets.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/IntTaxonomyFacets.java
index 498e638..bfc5ed5 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/IntTaxonomyFacets.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/IntTaxonomyFacets.java
@@ -31,13 +31,16 @@
 
 public abstract class IntTaxonomyFacets extends TaxonomyFacets {
 
+  /** Per-ordinal value. */
   protected final int[] values;
 
+  /** Sole constructor. */
   protected IntTaxonomyFacets(String indexFieldName, TaxonomyReader taxoReader, FacetsConfig config) throws IOException {
     super(indexFieldName, taxoReader, config);
     values = new int[taxoReader.getSize()];
   }
   
+  /** Rolls up any single-valued hierarchical dimensions. */
   protected void rollup() throws IOException {
     // Rollup any necessary dims:
     for(Map.Entry<String,DimConfig> ent : config.getDimConfigs().entrySet()) {
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/ParallelTaxonomyArrays.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/ParallelTaxonomyArrays.java
index e27ffe5..fbfd912 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/ParallelTaxonomyArrays.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/ParallelTaxonomyArrays.java
@@ -42,6 +42,10 @@
  */
 public abstract class ParallelTaxonomyArrays {
 
+  /** Sole constructor. */
+  public ParallelTaxonomyArrays() {
+  }
+
   /**
    * Returns the parents array, where {@code parents[i]} denotes the parent of
    * category ordinal {@code i}.
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/PrintTaxonomyStats.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/PrintTaxonomyStats.java
index b063ce2..e30e534 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/PrintTaxonomyStats.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/PrintTaxonomyStats.java
@@ -31,6 +31,11 @@
 // java -cp ../build/core/classes/java:../build/facet/classes/java org.apache.lucene.facet.util.PrintTaxonomyStats -printTree /s2/scratch/indices/wikibig.trunk.noparents.facets.Lucene41.nd1M/facets
 public class PrintTaxonomyStats {
 
+  /** Sole constructor. */
+  public PrintTaxonomyStats() {
+  }
+
+  /** Command-line tool. */
   public static void main(String[] args) throws IOException {
     boolean printTree = false;
     String path = null;
@@ -52,6 +57,7 @@
     dir.close();
   }
 
+  /** Recursively prints stats for all ordinals. */
   public static void printStats(TaxonomyReader r, PrintStream out, boolean printTree) throws IOException {
     out.println(r.getSize() + " total categories.");
 
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/SearcherTaxonomyManager.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/SearcherTaxonomyManager.java
index bb868ff..c4169ee 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/SearcherTaxonomyManager.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/SearcherTaxonomyManager.java
@@ -43,7 +43,10 @@
   /** Holds a matched pair of {@link IndexSearcher} and
    *  {@link TaxonomyReader} */
   public static class SearcherAndTaxonomy {
+    /** Point-in-time {@link IndexSearcher}. */
     public final IndexSearcher searcher;
+
+    /** Matching point-in-time {@link DirectoryTaxonomyReader}. */
     public final DirectoryTaxonomyReader taxonomyReader;
 
     /** Create a SearcherAndTaxonomy */
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacetSumValueSource.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacetSumValueSource.java
index dca4d4c..3839177 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacetSumValueSource.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacetSumValueSource.java
@@ -112,6 +112,11 @@
    *  hit; use this to aggregate the sum of all hit scores
    *  for each facet label.  */
   public static class ScoreValueSource extends ValueSource {
+
+    /** Sole constructor. */
+    public ScoreValueSource() {
+    }
+
     @Override
     public FunctionValues getValues(@SuppressWarnings("rawtypes") Map context, AtomicReaderContext readerContext) throws IOException {
       final Scorer scorer = (Scorer) context.get("scorer");
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacets.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacets.java
index c4ace0b..0c4d586 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacets.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacets.java
@@ -25,6 +25,7 @@
 
 import org.apache.lucene.facet.FacetResult;
 import org.apache.lucene.facet.Facets;
+import org.apache.lucene.facet.FacetsConfig.DimConfig; // javadocs
 import org.apache.lucene.facet.FacetsConfig;
 
 /** Base class for all taxonomy-based facets impls. */
@@ -43,12 +44,24 @@
     }
   };
 
+  /** Index field name provided to the constructor. */
   protected final String indexFieldName;
+
+  /** {@code TaxonomyReader} provided to the constructor. */
   protected final TaxonomyReader taxoReader;
+
+  /** {@code FacetsConfig} provided to the constructor. */
   protected final FacetsConfig config;
+
+  /** Maps parent ordinal to its child, or -1 if the parent
+   *  is childless. */
   protected final int[] children;
+
+  /** Maps an ordinal to its sibling, or -1 if there is no
+   *  sibling. */
   protected final int[] siblings;
 
+  /** Sole constructor. */
   protected TaxonomyFacets(String indexFieldName, TaxonomyReader taxoReader, FacetsConfig config) throws IOException {
     this.indexFieldName = indexFieldName;
     this.taxoReader = taxoReader;
@@ -58,6 +71,9 @@
     siblings = pta.siblings();
   }
 
+  /** Throws {@code IllegalArgumentException} if the
+   *  dimension is not recognized.  Otherwise, returns the
+   *  {@link DimConfig} for this dimension. */
   protected FacetsConfig.DimConfig verifyDim(String dim) {
     FacetsConfig.DimConfig dimConfig = config.getDimConfig(dim);
     if (!dimConfig.indexFieldName.equals(indexFieldName)) {
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyReader.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyReader.java
index 921f5b2..a7b2240 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyReader.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyReader.java
@@ -89,6 +89,10 @@
     }
     
   }
+
+  /** Sole constructor. */
+  public TaxonomyReader() {
+  }
   
   /**
    * The root category (the category with the empty path) always has the ordinal
@@ -142,7 +146,7 @@
   protected abstract TaxonomyReader doOpenIfChanged() throws IOException;
   
   /**
-   * @throws AlreadyClosedException if this IndexReader is closed
+   * Throws {@link AlreadyClosedException} if this IndexReader is closed
    */
   protected final void ensureOpen() throws AlreadyClosedException {
     if (getRefCount() <= 0) {
@@ -217,6 +221,7 @@
    */
   public abstract int getOrdinal(FacetLabel categoryPath) throws IOException;
 
+  /** Returns ordinal for the dim + path. */
   public int getOrdinal(String dim, String[] path) throws IOException {
     String[] fullPath = new String[path.length+1];
     fullPath[0] = dim;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyReader.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyReader.java
index 931e3b8..0d4d6ce 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyReader.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyReader.java
@@ -208,10 +208,14 @@
     }
   }
 
+  /** Open the {@link DirectoryReader} from this {@link
+   *  Directory}. */
   protected DirectoryReader openIndexReader(Directory directory) throws IOException {
     return DirectoryReader.open(directory);
   }
 
+  /** Open the {@link DirectoryReader} from this {@link
+   *  IndexWriter}. */
   protected DirectoryReader openIndexReader(IndexWriter writer) throws IOException {
     return DirectoryReader.open(writer, false);
   }
@@ -342,6 +346,9 @@
     }
   }
 
+  /** Returns ordinal -> label mapping, up to the provided
+   *  max ordinal or number of ordinals, whichever is
+   *  smaller. */
   public String toString(int max) {
     ensureOpen();
     StringBuilder sb = new StringBuilder();
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyWriter.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyWriter.java
index edf25f6..9d5b24d 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyWriter.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyWriter.java
@@ -326,6 +326,7 @@
     return new Cl2oTaxonomyWriterCache(1024, 0.15f, 3);
   }
 
+  /** Create this with {@code OpenMode.CREATE_OR_APPEND}. */
   public DirectoryTaxonomyWriter(Directory d) throws IOException {
     this(d, OpenMode.CREATE_OR_APPEND);
   }
@@ -840,12 +841,16 @@
      * and size-1.  
      */
     public void setSize(int size) throws IOException;
+
+    /** Record a mapping. */
     public void addMapping(int origOrdinal, int newOrdinal) throws IOException;
+
     /**
      * Call addDone() to say that all addMapping() have been done.
      * In some implementations this might free some resources. 
      */
     public void addDone() throws IOException;
+
     /**
      * Return the map from the taxonomy's original (consecutive) ordinals
      * to the new taxonomy's ordinals. If the map has to be read from disk
@@ -862,6 +867,11 @@
    */
   public static final class MemoryOrdinalMap implements OrdinalMap {
     int[] map;
+
+    /** Sole constructor. */
+    public MemoryOrdinalMap() {
+    }
+
     @Override
     public void setSize(int taxonomySize) {
       map = new int[taxonomySize];
@@ -885,6 +895,7 @@
     File tmpfile;
     DataOutputStream out;
 
+    /** Sole constructor. */
     public DiskOrdinalMap(File tmpfile) throws FileNotFoundException {
       this.tmpfile = tmpfile;
       out = new DataOutputStream(new BufferedOutputStream(
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/Cl2oTaxonomyWriterCache.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/Cl2oTaxonomyWriterCache.java
index abbac2d..9d678f0 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/Cl2oTaxonomyWriterCache.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/Cl2oTaxonomyWriterCache.java
@@ -39,6 +39,7 @@
   
   private volatile CompactLabelToOrdinal cache;
 
+  /** Sole constructor. */
   public Cl2oTaxonomyWriterCache(int initialCapcity, float loadFactor, int numHashArrays) {
     this.cache = new CompactLabelToOrdinal(initialCapcity, loadFactor, numHashArrays);
     this.initialCapcity = initialCapcity;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CollisionMap.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CollisionMap.java
index bcd3b9a..28cc8ee 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CollisionMap.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CollisionMap.java
@@ -70,10 +70,12 @@
     this.threshold = (int) (this.capacity * this.loadFactor);
   }
 
+  /** How many mappings. */
   public int size() {
     return this.size;
   }
 
+  /** How many slots are allocated. */
   public int capacity() {
     return this.capacity;
   }
@@ -103,6 +105,9 @@
     this.threshold = (int) (this.capacity * this.loadFactor);
   }
 
+  /** Return the mapping, or {@link
+   *  LabelToOrdinal#INVALID_ORDINAL} if the label isn't
+   *  recognized. */
   public int get(FacetLabel label, int hash) {
     int bucketIndex = indexFor(hash, this.capacity);
     Entry e = this.entries[bucketIndex];
@@ -117,6 +122,7 @@
     return e.cid;
   }
 
+  /** Add another mapping. */
   public int addLabel(FacetLabel label, int hash, int cid) {
     int bucketIndex = indexFor(hash, this.capacity);
     for (Entry e = this.entries[bucketIndex]; e != null; e = e.next) {
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CompactLabelToOrdinal.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CompactLabelToOrdinal.java
index 4db48a9..a9af612 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CompactLabelToOrdinal.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CompactLabelToOrdinal.java
@@ -55,6 +55,7 @@
  */
 public class CompactLabelToOrdinal extends LabelToOrdinal {
 
+  /** Default maximum load factor. */
   public static final float DefaultLoadFactor = 0.15f;
 
   static final char TERMINATOR_CHAR = 0xffff;
@@ -68,6 +69,7 @@
   private int threshold;
   private float loadFactor;
 
+  /** How many labels. */
   public int sizeOfMap() {
     return this.collisionMap.size();
   }
@@ -75,6 +77,7 @@
   private CompactLabelToOrdinal() {
   }
 
+  /** Sole constructor. */
   public CompactLabelToOrdinal(int initialCapacity, float loadFactor,
                                 int numHashArrays) {
 
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LabelToOrdinal.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LabelToOrdinal.java
index 33b60fe..49473be 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LabelToOrdinal.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LabelToOrdinal.java
@@ -26,9 +26,17 @@
  */
 public abstract class LabelToOrdinal {
 
+  /** How many ordinals we've seen. */
   protected int counter;
+
+  /** Returned by {@link #getOrdinal} when the label isn't
+   *  recognized. */
   public static final int INVALID_ORDINAL = -2;
 
+  /** Default constructor. */
+  public LabelToOrdinal() {
+  }
+
   /**
    * return the maximal Ordinal assigned so far
    */
@@ -52,7 +60,7 @@
   public abstract void addLabel(FacetLabel label, int ordinal);
 
   /**
-   * @return the ordinal assigned to the given label, 
+   * Returns the ordinal assigned to the given label, 
    * or {@link #INVALID_ORDINAL} if the label cannot be found in this table.
    */
   public abstract int getOrdinal(FacetLabel label);
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LruTaxonomyWriterCache.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LruTaxonomyWriterCache.java
index 7bdbb2c..1393a0d 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LruTaxonomyWriterCache.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LruTaxonomyWriterCache.java
@@ -32,10 +32,19 @@
    * For guaranteed correctness - not relying on no-collisions in the hash
    * function, LRU_STRING should be used.
    */
-  public enum LRUType { LRU_HASHED, LRU_STRING }
+  public enum LRUType {
+    /** Use the label's hash as the key; this can lead to
+     *  silent conflicts! */
+    LRU_HASHED,
+
+    /** Use the label as the hash key; this is always
+     *  correct but will usually use more RAM. */
+    LRU_STRING
+  }
 
   private NameIntCacheLRU cache;
 
+  /** Creates this with {@link LRUType#LRU_HASHED} method. */
   public LruTaxonomyWriterCache(int cacheSize) {
     // TODO (Facet): choose between NameHashIntCacheLRU and NameIntCacheLRU.
     // For guaranteed correctness - not relying on no-collisions in the hash
@@ -46,6 +55,7 @@
     this(cacheSize, LRUType.LRU_HASHED);
   }
 
+  /** Creates this with the specified method. */
   public LruTaxonomyWriterCache(int cacheSize, LRUType lruType) {
     // TODO (Facet): choose between NameHashIntCacheLRU and NameIntCacheLRU.
     // For guaranteed correctness - not relying on no-collisions in the hash
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/NameIntCacheLRU.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/NameIntCacheLRU.java
index f43b6b1..1626ada 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/NameIntCacheLRU.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/NameIntCacheLRU.java
@@ -42,10 +42,12 @@
     createCache(maxCacheSize);
   }
 
+  /** Maximum number of cache entries before eviction. */
   public int getMaxSize() {
     return maxCacheSize;
   }
   
+  /** Number of entries currently in the cache. */
   public int getSize() {
     return cache.size();
   }