You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by mi...@apache.org on 2012/03/20 18:28:24 UTC
svn commit: r1303025 - in /lucene/dev/trunk: ./ lucene/
lucene/core/src/java/org/apache/lucene/util/fst/
Author: mikemccand
Date: Tue Mar 20 17:28:23 2012
New Revision: 1303025
URL: http://svn.apache.org/viewvc?rev=1303025&view=rev
Log:
improve FST javadocs
Modified:
lucene/dev/trunk/ (props changed)
lucene/dev/trunk/lucene/ (props changed)
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Builder.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/ByteSequenceOutputs.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/BytesRefFSTEnum.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/FST.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/IntSequenceOutputs.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/IntsRefFSTEnum.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/NoOutputs.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Outputs.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/PairOutputs.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/PositiveIntOutputs.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/UpToTwoPositiveIntOutputs.java
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Util.java
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Builder.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Builder.java?rev=1303025&r1=1303024&r2=1303025&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Builder.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Builder.java Tue Mar 20 17:28:23 2012
@@ -26,8 +26,8 @@ import org.apache.lucene.util.fst.FST.IN
/**
* Builds a minimal FST (maps an IntsRef term to an arbitrary
- * output) from pre-sorted terms with outputs (the FST
- * becomes an FSA if you use NoOutputs). The FST is written
+ * output) from pre-sorted terms with outputs. The FST
+ * 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
- // something "custom" as suffixes are "frozen":
+ /** Expert: this is invoked by Builder whenever a suffix
+ * 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;
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/ByteSequenceOutputs.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/ByteSequenceOutputs.java?rev=1303025&r1=1303024&r2=1303025&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/ByteSequenceOutputs.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/ByteSequenceOutputs.java Tue Mar 20 17:28:23 2012
@@ -24,7 +24,8 @@ import org.apache.lucene.store.DataOutpu
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
*/
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/BytesRefFSTEnum.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/BytesRefFSTEnum.java?rev=1303025&r1=1303024&r2=1303025&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/BytesRefFSTEnum.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/BytesRefFSTEnum.java Tue Mar 20 17:28:23 2012
@@ -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> ex
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;
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/FST.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/FST.java?rev=1303025&r1=1303024&r2=1303025&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/FST.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/FST.java Tue Mar 20 17:28:23 2012
@@ -56,7 +56,8 @@ import org.apache.lucene.util.fst.Builde
// 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.Builde
* @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;
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/IntSequenceOutputs.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/IntSequenceOutputs.java?rev=1303025&r1=1303024&r2=1303025&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/IntSequenceOutputs.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/IntSequenceOutputs.java Tue Mar 20 17:28:23 2012
@@ -24,7 +24,8 @@ import org.apache.lucene.store.DataOutpu
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
*/
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/IntsRefFSTEnum.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/IntsRefFSTEnum.java?rev=1303025&r1=1303024&r2=1303025&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/IntsRefFSTEnum.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/IntsRefFSTEnum.java Tue Mar 20 17:28:23 2012
@@ -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> ext
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;
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/NoOutputs.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/NoOutputs.java?rev=1303025&r1=1303024&r2=1303025&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/NoOutputs.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/NoOutputs.java Tue Mar 20 17:28:23 2012
@@ -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
*/
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Outputs.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Outputs.java?rev=1303025&r1=1303024&r2=1303025&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Outputs.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Outputs.java Tue Mar 20 17:28:23 2012
@@ -24,7 +24,7 @@ import org.apache.lucene.store.DataOutpu
/**
* 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
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/PairOutputs.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/PairOutputs.java?rev=1303025&r1=1303024&r2=1303025&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/PairOutputs.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/PairOutputs.java Tue Mar 20 17:28:23 2012
@@ -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 Ou
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;
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/PositiveIntOutputs.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/PositiveIntOutputs.java?rev=1303025&r1=1303024&r2=1303025&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/PositiveIntOutputs.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/PositiveIntOutputs.java Tue Mar 20 17:28:23 2012
@@ -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
- * resulting FST is not guaranteed to be minimal! See
- * {@link Builder}.
+ * An FST {@link Outputs} implementation where each output
+ * is a non-negative long value.
*
* @lucene.experimental
*/
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/UpToTwoPositiveIntOutputs.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/UpToTwoPositiveIntOutputs.java?rev=1303025&r1=1303024&r2=1303025&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/UpToTwoPositiveIntOutputs.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/UpToTwoPositiveIntOutputs.java Tue Mar 20 17:28:23 2012
@@ -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.DataOutpu
public final class UpToTwoPositiveIntOutputs extends Outputs<Object> {
+ /** Holds two long outputs. */
public final static class TwoLongs {
public final long first;
public final long second;
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Util.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Util.java?rev=1303025&r1=1303024&r2=1303025&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Util.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/fst/Util.java Tue Mar 20 17:28:23 2012
@@ -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;