improve FST javadocs

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1303025 13f79535-47bb-0310-9956-ffa450edef68

lucene/core/src/java/org/apache/lucene/util/fst/Builder.java

@@ -26,8 +26,8 @@ import org.apache.lucene.util.fst.FST.INPUT_TYPE; // javadoc
 
 /**
  * Builds a minimal FST (maps an IntsRef term to an arbitrary
- * output) from pre-sorted terms with outputs (the FST
+ * output) from pre-sorted terms with outputs.  The FST
- * becomes an FSA if you use NoOutputs).  The FST is written
+ * becomes an FSA if you use NoOutputs.  The FST is written
  * on-the-fly into a compact serialized format byte array, which can
  * be saved to / loaded from a Directory or used directly
  * for traversal.  The FST is always finite (no cycles).
@@ -68,8 +68,8 @@ public class Builder<T> {
   // current "frontier"
   private UnCompiledNode<T>[] frontier;
 
-  // Expert: you pass an instance of this if you want to do
+  /** Expert: this is invoked by Builder whenever a suffix
-  // something "custom" as suffixes are "frozen":
+   *  is serialized. */
   public static abstract class FreezeTail<T> {
     public abstract void freeze(final UnCompiledNode<T>[] frontier, int prefixLenPlus1, IntsRef prevInput) throws IOException;
   }
@@ -470,6 +470,7 @@ public class Builder<T> {
     }
   }
 
+  /** Expert: holds a pending (seen but not yet serialized) arc. */
   public static class Arc<T> {
     public int label;                             // really an "unsigned" byte
     public Node target;
@@ -493,6 +494,7 @@ public class Builder<T> {
     }
   }
 
+  /** Expert: holds a pending (seen but not yet serialized) Node. */
   public static final class UnCompiledNode<T> implements Node {
     final Builder<T> owner;
     public int numArcs;

lucene/core/src/java/org/apache/lucene/util/fst/ByteSequenceOutputs.java

@@ -24,7 +24,8 @@ import org.apache.lucene.store.DataOutput;
 import org.apache.lucene.util.BytesRef;
 
 /**
- * Output is a sequence of bytes, for each input term.
+ * An FST {@link Outputs} implementation where each output
+ * is a sequence of bytes.
  *
  * @lucene.experimental
  */

lucene/core/src/java/org/apache/lucene/util/fst/BytesRefFSTEnum.java

@@ -21,7 +21,8 @@ import java.io.IOException;
 
 import org.apache.lucene.util.BytesRef;
 
-/** Can next() and advance() through the terms in an FST
+/** Enumerates all input (BytesRef) + output pairs in an
+ *  FST.
  *
   * @lucene.experimental
 */
@@ -31,6 +32,7 @@ public final class BytesRefFSTEnum<T> extends FSTEnum<T> {
   private final InputOutput<T> result = new InputOutput<T>();
   private BytesRef target;
 
+  /** Holds a single input (BytesRef) + output pair. */
   public static class InputOutput<T> {
     public BytesRef input;
     public T output;

lucene/core/src/java/org/apache/lucene/util/fst/FST.java

@@ -56,7 +56,8 @@ import org.apache.lucene.util.fst.Builder.UnCompiledNode;
 // dead-end state (NON_FINAL_END_NODE=0), the layers above
 // (FSTEnum, Util) have problems with this!!
 
-/** Represents an FST using a compact byte[] format.
+/** Represents an finite state machine (FST), using a
+ *  compact byte[] format.
  *  <p> The format is similar to what's used by Morfologik
  *  (http://sourceforge.net/projects/morfologik).
  *
@@ -66,6 +67,8 @@ import org.apache.lucene.util.fst.Builder.UnCompiledNode;
  * @lucene.experimental
  */
 public final class FST<T> {
+  /** Specifies allowed range of each int input label for
+   *  this FST. */
   public static enum INPUT_TYPE {BYTE1, BYTE2, BYTE4};
   public final INPUT_TYPE inputType;
 
@@ -159,6 +162,7 @@ public final class FST<T> {
 
   private Arc<T> cachedRootArcs[];
 
+  /** Represents a single arc. */
   public final static class Arc<T> {
     public int label;
     public T output;
@@ -1226,7 +1230,10 @@ public final class FST<T> {
     }
   }
 
-  /** Expert */
+  /** Reads the bytes from this FST.  Use {@link
+   *  #getBytesReader(int)} to obtain an instance for this
+   *  FST; re-use across calls (but only within a single
+   *  thread) for better performance. */
   public static abstract class BytesReader extends DataInput {
     protected int pos;
     protected final byte[] bytes;

lucene/core/src/java/org/apache/lucene/util/fst/IntSequenceOutputs.java

@@ -24,7 +24,8 @@ import org.apache.lucene.store.DataOutput;
 import org.apache.lucene.util.IntsRef;
 
 /**
- * Output is a sequence of ints, for each input term.
+ * An FST {@link Outputs} implementation where each output
+ * is a sequence of ints.
  *
  * @lucene.experimental
  */

lucene/core/src/java/org/apache/lucene/util/fst/IntsRefFSTEnum.java

@@ -21,7 +21,8 @@ import org.apache.lucene.util.IntsRef;
 
 import java.io.IOException;
 
-/** Can next() and advance() through the terms in an FST
+/** Enumerates all input (IntsRef) + output pairs in an
+ *  FST.
  *
   * @lucene.experimental
 */
@@ -31,6 +32,7 @@ public final class IntsRefFSTEnum<T> extends FSTEnum<T> {
   private final InputOutput<T> result = new InputOutput<T>();
   private IntsRef target;
 
+  /** Holds a single input (IntsRef) + output pair. */
   public static class InputOutput<T> {
     public IntsRef input;
     public T output;

lucene/core/src/java/org/apache/lucene/util/fst/NoOutputs.java

@@ -21,7 +21,8 @@ import org.apache.lucene.store.DataInput;
 import org.apache.lucene.store.DataOutput;
 
 /**
- * Use this if you just want to build an FSA.
+ * A null FST {@link Outputs} implementation; use this if
+ * you just want to build an FSA.
  *
  * @lucene.experimental
  */

lucene/core/src/java/org/apache/lucene/util/fst/Outputs.java

@@ -24,7 +24,7 @@ import org.apache.lucene.store.DataOutput;
 
 /**
  * Represents the outputs for an FST, providing the basic
- * algebra needed for the FST.
+ * algebra required for building and traversing the FST.
  *
  * <p>Note that any operation that returns NO_OUTPUT must
  * return the same singleton object from {@link

lucene/core/src/java/org/apache/lucene/util/fst/PairOutputs.java

@@ -23,7 +23,7 @@ import org.apache.lucene.store.DataInput;
 import org.apache.lucene.store.DataOutput;
 
 /**
- * Pairs up two outputs into one.
+ * An FST {@link Outputs} implementation, holding two other outputs.
  *
  * @lucene.experimental
  */
@@ -34,6 +34,7 @@ public class PairOutputs<A,B> extends Outputs<PairOutputs.Pair<A,B>> {
   private final Outputs<A> outputs1;
   private final Outputs<B> outputs2;
 
+  /** Holds a single pair of two outputs. */
   public static class Pair<A,B> {
     public final A output1;
     public final B output2;

lucene/core/src/java/org/apache/lucene/util/fst/PositiveIntOutputs.java

@@ -23,9 +23,8 @@ import org.apache.lucene.store.DataInput;
 import org.apache.lucene.store.DataOutput;
 
 /**
- * Output is a long, for each input term.  NOTE: the
+ * An FST {@link Outputs} implementation where each output
- * resulting FST is not guaranteed to be minimal!  See
+ * is a non-negative long value.
- * {@link Builder}.
  *
  * @lucene.experimental
  */

lucene/core/src/java/org/apache/lucene/util/fst/UpToTwoPositiveIntOutputs.java

@@ -23,7 +23,8 @@ import org.apache.lucene.store.DataInput;
 import org.apache.lucene.store.DataOutput;
 
 /**
- * Holds one or two longs for each input term.  If it's a
+ * An FST {@link Outputs} implementation where each output
+ * is one or two non-negative long values.  If it's a
  * single output, Long is returned; else, TwoLongs.  Order
  * is preserved in the TwoLongs case, ie .first is the first
  * input/output added to Builder, and .second is the
@@ -38,6 +39,7 @@ import org.apache.lucene.store.DataOutput;
 
 public final class UpToTwoPositiveIntOutputs extends Outputs<Object> {
 
+  /** Holds two long outputs. */
   public final static class TwoLongs {
     public final long first;
     public final long second;

lucene/core/src/java/org/apache/lucene/util/fst/Util.java

@@ -23,7 +23,7 @@ import java.util.*;
 import org.apache.lucene.util.BytesRef;
 import org.apache.lucene.util.IntsRef;
 
-/** Static helper methods
+/** Static helper methods.
  *
  * @lucene.experimental */
 public final class Util {
@@ -496,6 +496,8 @@ public final class Util {
     }
   }
 
+  /** Holds a single input (IntsRef) + output, returned by
+   *  {@link #shortestPaths}. */
   public final static class MinResult<T> implements Comparable<MinResult<T>> {
     public final IntsRef input;
     public final T output;