Lucene.Net.Core.Util.Fst: documentation comments
Project: http://git-wip-us.apache.org/repos/asf/lucenenet/repo Commit: http://git-wip-us.apache.org/repos/asf/lucenenet/commit/3724588b Tree: http://git-wip-us.apache.org/repos/asf/lucenenet/tree/3724588b Diff: http://git-wip-us.apache.org/repos/asf/lucenenet/diff/3724588b Branch: refs/heads/api-work Commit: 3724588b293b44ba493490233392b00f69820c31 Parents: 93f3f48 Author: Shad Storhaug <[email protected]> Authored: Fri Mar 24 08:48:28 2017 +0700 Committer: Shad Storhaug <[email protected]> Committed: Fri Mar 24 08:48:28 2017 +0700 ---------------------------------------------------------------------- src/Lucene.Net.Core/Util/Fst/Builder.cs | 61 +++++---- .../Util/Fst/ByteSequenceOutputs.cs | 4 +- src/Lucene.Net.Core/Util/Fst/BytesRefFSTEnum.cs | 22 ++-- src/Lucene.Net.Core/Util/Fst/BytesStore.cs | 22 ++-- .../Util/Fst/CharSequenceOutputs.cs | 4 +- src/Lucene.Net.Core/Util/Fst/FST.cs | 124 +++++++++++-------- src/Lucene.Net.Core/Util/Fst/FSTEnum.cs | 26 ++-- .../Util/Fst/ForwardBytesReader.cs | 2 +- .../Util/Fst/IntSequenceOutputs.cs | 4 +- src/Lucene.Net.Core/Util/Fst/IntsRefFSTEnum.cs | 22 ++-- src/Lucene.Net.Core/Util/Fst/NoOutputs.cs | 10 +- src/Lucene.Net.Core/Util/Fst/NodeHash.cs | 18 ++- src/Lucene.Net.Core/Util/Fst/Outputs.cs | 28 ++--- src/Lucene.Net.Core/Util/Fst/PairOutputs.cs | 4 +- .../Util/Fst/PositiveIntOutputs.cs | 4 +- .../Util/Fst/ReverseBytesReader.cs | 2 +- src/Lucene.Net.Core/Util/Fst/Util.cs | 118 +++++++++--------- 17 files changed, 253 insertions(+), 222 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/Builder.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/Builder.cs b/src/Lucene.Net.Core/Util/Fst/Builder.cs index 7cb2c16..d87b3b3 100644 --- a/src/Lucene.Net.Core/Util/Fst/Builder.cs +++ b/src/Lucene.Net.Core/Util/Fst/Builder.cs @@ -29,23 +29,23 @@ namespace Lucene.Net.Util.Fst // build it? /// <summary> - /// Builds a minimal FST (maps an IntsRef term to an arbitrary + /// Builds a minimal FST (maps an <see cref="Int32sRef"/> term to an arbitrary /// 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). /// - /// <p>NOTE: The algorithm is described at - /// http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.24.3698</p> + /// <para/>NOTE: The algorithm is described at + /// http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.24.3698 /// - /// <p>The parameterized type T is the output type. See the - /// subclasses of <seealso cref="Outputs"/>. + /// <para/>The parameterized type <typeparam name="T"/> is the output type. See the + /// subclasses of <see cref="Outputs{T}"/>. /// - /// <p>FSTs larger than 2.1GB are now possible (as of Lucene + /// <para/>FSTs larger than 2.1GB are now possible (as of Lucene /// 4.2). FSTs containing more than 2.1B nodes are also now /// possible, however they cannot be packed. - /// + /// <para/> /// @lucene.experimental /// </summary> public class Builder<T> : Builder @@ -99,9 +99,8 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Instantiates an FST/FSA builder without any pruning. A shortcut - /// to {@link #Builder(FST.INPUT_TYPE, int, int, boolean, - /// boolean, int, Outputs, FreezeTail, boolean, float, - /// boolean, int)} with pruning options turned off. + /// to <see cref="Builder.Builder(FST.INPUT_TYPE, int, int, bool, bool, int, Outputs{T}, FreezeTail{T}, bool, float, bool, int)"/> + /// with pruning options turned off. /// </summary> public Builder(FST.INPUT_TYPE inputType, Outputs<T> outputs) : this(inputType, 0, 0, true, true, int.MaxValue, outputs, null, false, PackedInt32s.COMPACT, true, 15) @@ -114,9 +113,9 @@ namespace Lucene.Net.Util.Fst /// tweaks. Read parameter documentation carefully. /// </summary> /// <param name="inputType"> - /// The input type (transition labels). Can be anything from <seealso cref="INPUT_TYPE"/> + /// The input type (transition labels). Can be anything from <see cref="Lucene.Net.Util.Fst.FST.INPUT_TYPE"/> /// enumeration. Shorter types will consume less memory. Strings (character sequences) are - /// represented as <seealso cref="INPUT_TYPE#BYTE4"/> (full unicode codepoints). + /// represented as <see cref="Lucene.Net.Util.Fst.FST.INPUT_TYPE.BYTE4"/> (full unicode codepoints). /// </param> /// <param name="minSuffixCount1"> /// If pruning the input graph during construction, this threshold is used for telling @@ -127,36 +126,36 @@ namespace Lucene.Net.Util.Fst /// (Note: only Mike McCandless knows what this one is really doing...) /// </param> /// <param name="doShareSuffix"> - /// If <code>true</code>, the shared suffixes will be compacted into unique paths. + /// If <c>true</c>, the shared suffixes will be compacted into unique paths. /// this requires an additional RAM-intensive hash map for lookups in memory. Setting this parameter to - /// <code>false</code> creates a single suffix path for all input sequences. this will result in a larger + /// <c>false</c> creates a single suffix path for all input sequences. this will result in a larger /// FST, but requires substantially less memory and CPU during building. /// </param> /// <param name="doShareNonSingletonNodes"> - /// Only used if doShareSuffix is true. Set this to + /// Only used if <paramref name="doShareSuffix"/> is <c>true</c>. Set this to /// true to ensure FST is fully minimal, at cost of more /// CPU and more RAM during building. /// </param> /// <param name="shareMaxTailLength"> - /// Only used if doShareSuffix is true. Set this to - /// Integer.MAX_VALUE to ensure FST is fully minimal, at cost of more + /// Only used if <paramref name="doShareSuffix"/> is <c>true</c>. Set this to + /// <see cref="int.MaxValue"/> to ensure FST is fully minimal, at cost of more /// CPU and more RAM during building. /// </param> /// <param name="outputs"> The output type for each input sequence. Applies only if building an FST. For - /// FSA, use <seealso cref="NoOutputs.Singleton"/> and <seealso cref="NoOutputs.NoOutput"/> as the + /// FSA, use <see cref="NoOutputs.Singleton"/> and <see cref="NoOutputs.NoOutput"/> as the /// singleton output object. /// </param> - /// <param name="doPackFST"> Pass true to create a packed FST. + /// <param name="doPackFST"> Pass <c>true</c> to create a packed FST. + /// </param> + /// <param name="acceptableOverheadRatio"> How to trade speed for space when building the FST. this option + /// is only relevant when doPackFST is true. <see cref="PackedInt32s.GetMutable(int, int, float)"/> /// </param> - /// <param name="acceptableOverheadRatio"> How to trade speed for space when building the FST. this option </param> - /// is only relevant when doPackFST is true. <seealso cref= PackedInt32s#getMutable(int, int, float) - /// </seealso> /// <param name="allowArrayArcs"> Pass false to disable the array arc optimization /// while building the FST; this will make the resulting /// FST smaller but slower to traverse. /// </param> /// <param name="bytesPageBits"> How many bits wide to make each - /// byte[] block in the BytesStore; if you know the FST + /// <see cref="T:byte[]"/> block in the <see cref="BytesStore"/>; if you know the FST /// will be large then make this larger. For example 15 /// bits = 32768 byte pages. </param> public Builder(FST.INPUT_TYPE inputType, int minSuffixCount1, int minSuffixCount2, bool doShareSuffix, @@ -367,13 +366,13 @@ namespace Lucene.Net.Util.Fst /// <summary> /// It's OK to add the same input twice in a row with - /// different outputs, as long as outputs impls the merge - /// method. Note that input is fully consumed after this - /// method is returned (so caller is free to reuse), but - /// output is not. So if your outputs are changeable (eg - /// <seealso cref="ByteSequenceOutputs"/> or {@link - /// IntSequenceOutputs}) then you cannot reuse across - /// calls. + /// different outputs, as long as outputs impls the merge + /// method. Note that input is fully consumed after this + /// method is returned (so caller is free to reuse), but + /// output is not. So if your outputs are changeable (eg + /// <see cref="ByteSequenceOutputs"/> or + /// <see cref="Int32SequenceOutputs"/>) then you cannot reuse across + /// calls. /// </summary> public virtual void Add(Int32sRef input, T output) { @@ -518,7 +517,7 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Returns final FST. NOTE: this will return null if - /// nothing is accepted by the FST. + /// nothing is accepted by the FST. /// </summary> public virtual FST<T> Finish() { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/ByteSequenceOutputs.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/ByteSequenceOutputs.cs b/src/Lucene.Net.Core/Util/Fst/ByteSequenceOutputs.cs index 7f41142..1c69881 100644 --- a/src/Lucene.Net.Core/Util/Fst/ByteSequenceOutputs.cs +++ b/src/Lucene.Net.Core/Util/Fst/ByteSequenceOutputs.cs @@ -24,9 +24,9 @@ namespace Lucene.Net.Util.Fst using DataOutput = Lucene.Net.Store.DataOutput; /// <summary> - /// An FST <seealso cref="Outputs"/> implementation where each output + /// An FST <see cref="T:Outputs{BytesRef}"/> implementation where each output /// is a sequence of bytes. - /// + /// <para/> /// @lucene.experimental /// </summary> public sealed class ByteSequenceOutputs : Outputs<BytesRef> http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/BytesRefFSTEnum.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/BytesRefFSTEnum.cs b/src/Lucene.Net.Core/Util/Fst/BytesRefFSTEnum.cs index 9d985a8..7b0c6fe 100644 --- a/src/Lucene.Net.Core/Util/Fst/BytesRefFSTEnum.cs +++ b/src/Lucene.Net.Core/Util/Fst/BytesRefFSTEnum.cs @@ -20,8 +20,8 @@ namespace Lucene.Net.Util.Fst */ /// <summary> - /// Enumerates all input (BytesRef) + output pairs in an - /// FST. + /// Enumerates all input (<see cref="BytesRef"/>) + output pairs in an + /// FST. /// /// @lucene.experimental /// </summary> @@ -35,8 +35,8 @@ namespace Lucene.Net.Util.Fst /// <summary> /// doFloor controls the behavior of advance: if it's true - /// doFloor is true, advance positions to the biggest - /// term before target. + /// doFloor is true, advance positions to the biggest + /// term before target. /// </summary> public BytesRefFSTEnum(FST<T> fst) : base(fst) @@ -58,7 +58,7 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Seeks to smallest term that's >= target. </summary> + /// Seeks to smallest term that's >= target. </summary> public BytesRefFSTEnum.InputOutput<T> SeekCeil(BytesRef target) { this.target = target; @@ -68,7 +68,7 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Seeks to biggest term that's <= target. </summary> + /// Seeks to biggest term that's <= target. </summary> public BytesRefFSTEnum.InputOutput<T> SeekFloor(BytesRef target) { this.target = target; @@ -78,10 +78,10 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Seeks to exactly this term, returning null if the term - /// doesn't exist. this is faster than using {@link - /// #seekFloor} or <seealso cref="#seekCeil"/> because it - /// short-circuits as soon the match is not found. + /// Seeks to exactly this term, returning <c>null</c> if the term + /// doesn't exist. This is faster than using + /// <see cref="SeekFloor"/> or <see cref="SeekCeil"/> because it + /// short-circuits as soon the match is not found. /// </summary> public BytesRefFSTEnum.InputOutput<T> SeekExact(BytesRef target) { @@ -157,7 +157,7 @@ namespace Lucene.Net.Util.Fst { } /// <summary> - /// Holds a single input (BytesRef) + output pair. </summary> + /// Holds a single input (<see cref="BytesRef"/>) + output pair. </summary> public class InputOutput<T> { public BytesRef Input { get; set; } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/BytesStore.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/BytesStore.cs b/src/Lucene.Net.Core/Util/Fst/BytesStore.cs index 294165f..0d2e5da 100644 --- a/src/Lucene.Net.Core/Util/Fst/BytesStore.cs +++ b/src/Lucene.Net.Core/Util/Fst/BytesStore.cs @@ -46,7 +46,7 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Pulls bytes from the provided IndexInput. </summary> + /// Pulls bytes from the provided <see cref="Store.IndexInput"/>. </summary> public BytesStore(DataInput @in, long numBytes, int maxBlockSize) { int blockSize = 2; @@ -74,8 +74,8 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Absolute write byte; you must ensure dest is < max - /// position written so far. + /// Absolute write byte; you must ensure dest is < max + /// position written so far. /// </summary> public virtual void WriteByte(int dest, byte b) { @@ -131,8 +131,8 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Absolute writeBytes without changing the current - /// position. Note: this cannot "grow" the bytes, so you - /// must only call it on already written parts. + /// position. Note: this cannot "grow" the bytes, so you + /// must only call it on already written parts. /// </summary> internal virtual void WriteBytes(long dest, byte[] b, int offset, int len) { @@ -198,8 +198,8 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Absolute copy bytes self to self, without changing the - /// position. Note: this cannot "grow" the bytes, so must - /// only call it on already written parts. + /// position. Note: this cannot "grow" the bytes, so must + /// only call it on already written parts. /// </summary> public virtual void CopyBytes(long src, long dest, int len) { @@ -265,7 +265,7 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Writes an int at the absolute position without + /// Writes an <see cref="int"/> at the absolute position without /// changing the current pointer. /// <para/> /// NOTE: This was writeInt() in Lucene @@ -290,7 +290,7 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Reverse from srcPos, inclusive, to destPos, inclusive. </summary> + /// Reverse from <paramref name="srcPos"/>, inclusive, to <paramref name="destPos"/>, inclusive. </summary> public virtual void Reverse(long srcPos, long destPos) { Debug.Assert(srcPos < destPos); @@ -363,7 +363,7 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Pos must be less than the max position written so far! - /// Ie, you cannot "grow" the file with this! + /// i.e., you cannot "grow" the file with this! /// </summary> public virtual void Truncate(long newLen) { @@ -400,7 +400,7 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Writes all of our bytes to the target <seealso cref="DataOutput"/>. </summary> + /// Writes all of our bytes to the target <see cref="DataOutput"/>. </summary> public virtual void WriteTo(DataOutput @out) { foreach (byte[] block in blocks) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/CharSequenceOutputs.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/CharSequenceOutputs.cs b/src/Lucene.Net.Core/Util/Fst/CharSequenceOutputs.cs index 36e4297..dee3ef2 100644 --- a/src/Lucene.Net.Core/Util/Fst/CharSequenceOutputs.cs +++ b/src/Lucene.Net.Core/Util/Fst/CharSequenceOutputs.cs @@ -24,9 +24,9 @@ namespace Lucene.Net.Util.Fst using DataOutput = Lucene.Net.Store.DataOutput; /// <summary> - /// An FST <seealso cref="Outputs"/> implementation where each output + /// An FST <see cref="Outputs{T}"/> implementation where each output /// is a sequence of characters. - /// + /// <para/> /// @lucene.experimental /// </summary> public sealed class CharSequenceOutputs : Outputs<CharsRef> http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/FST.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/FST.cs b/src/Lucene.Net.Core/Util/Fst/FST.cs index 4f290fe..8049e20 100644 --- a/src/Lucene.Net.Core/Util/Fst/FST.cs +++ b/src/Lucene.Net.Core/Util/Fst/FST.cs @@ -50,13 +50,13 @@ namespace Lucene.Net.Util.Fst /// <summary> /// 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). - /// - /// <p> See the {@link Lucene.Net.Util.Fst package - /// documentation} for some simple examples. + /// compact <see cref="T:byte[]"/> format. + /// <para/> The format is similar to what's used by Morfologik + /// (http://sourceforge.net/projects/morfologik). /// + /// <para/> See the <a href="https://lucene.apache.org/core/4_8_0/core/org/apache/lucene/util/fst/package-summary.html";> + /// FST package documentation</a> for some simple examples. + /// <para/> /// @lucene.experimental /// </summary> public sealed class FST<T> @@ -230,8 +230,8 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Load a previously saved FST; maxBlockBits allows you to - /// control the size of the byte[] pages used to hold the FST bytes. + /// Load a previously saved FST; <paramref name="maxBlockBits"/> allows you to + /// control the size of the <see cref="T:byte[]"/> pages used to hold the FST bytes. /// </summary> public FST(DataInput @in, Outputs<T> outputs, int maxBlockBits) { @@ -633,8 +633,8 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// returns true if the node at this address has any - /// outgoing arcs + /// returns <c>true</c> if the node at this address has any + /// outgoing arcs /// </summary> public static bool TargetHasArcs(FST.Arc<T> arc) { @@ -865,7 +865,7 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Fills virtual 'start' arc, ie, an empty incoming arc to - /// the FST's start node + /// the FST's start node /// </summary> public FST.Arc<T> GetFirstArc(FST.Arc<T> arc) { @@ -892,12 +892,12 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Follows the <code>follow</code> arc and reads the last - /// arc of its target; this changes the provided - /// <code>arc</code> (2nd arg) in-place and returns it. + /// Follows the <paramref name="follow"/> arc and reads the last + /// arc of its target; this changes the provided + /// <paramref name="arc"/> (2nd arg) in-place and returns it. /// </summary> /// <returns> Returns the second argument - /// (<code>arc</code>). </returns> + /// (<paramref name="arc"/>). </returns> public FST.Arc<T> ReadLastTargetArc(FST.Arc<T> follow, FST.Arc<T> arc, FST.BytesReader @in) { //System.out.println("readLast"); @@ -991,11 +991,11 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Follow the <code>follow</code> arc and read the first arc of its target; - /// this changes the provided <code>arc</code> (2nd arg) in-place and returns + /// Follow the <paramref name="follow"/> arc and read the first arc of its target; + /// this changes the provided <paramref name="arc"/> (2nd arg) in-place and returns /// it. /// </summary> - /// <returns> Returns the second argument (<code>arc</code>). </returns> + /// <returns> Returns the second argument (<paramref name="arc"/>). </returns> public FST.Arc<T> ReadFirstTargetArc(FST.Arc<T> follow, FST.Arc<T> arc, FST.BytesReader @in) { //int pos = address; @@ -1063,9 +1063,9 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Checks if <code>arc</code>'s target state is in expanded (or vector) format. + /// Checks if <paramref name="arc"/>'s target state is in expanded (or vector) format. /// </summary> - /// <returns> Returns <code>true</code> if <code>arc</code> points to a state in an + /// <returns> Returns <c>true</c> if <paramref name="arc"/> points to a state in an /// expanded array format. </returns> internal bool IsExpandedTarget(FST.Arc<T> follow, FST.BytesReader @in) { @@ -1100,8 +1100,8 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Peeks at next arc's label; does not alter arc. Do - /// not call this if arc.isLast()! + /// Peeks at next arc's label; does not alter <paramref name="arc"/>. Do + /// not call this if arc.IsLast! /// </summary> public int ReadNextArcLabel(FST.Arc<T> arc, FST.BytesReader @in) { @@ -1157,8 +1157,8 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Never returns null, but you should never call this if - /// arc.isLast() is true. + /// Never returns <c>null</c>, but you should never call this if + /// arc.IsLast is <c>true</c>. /// </summary> public FST.Arc<T> ReadNextRealArc(FST.Arc<T> arc, FST.BytesReader @in) { @@ -1278,8 +1278,8 @@ namespace Lucene.Net.Util.Fst // look automaton? /// <summary> - /// Finds an arc leaving the incoming arc, replacing the arc in place. - /// this returns null if the arc was not found, else the incoming arc. + /// Finds an arc leaving the incoming <paramref name="arc"/>, replacing the arc in place. + /// this returns <c>null</c> if the arc was not found, else the incoming <paramref name="arc"/>. /// </summary> public FST.Arc<T> FindTargetArc(int labelToMatch, FST.Arc<T> follow, FST.Arc<T> arc, FST.BytesReader @in) { @@ -1472,25 +1472,25 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Nodes will be expanded if their depth (distance from the root node) is /// <= this value and their number of arcs is >= - /// <seealso cref="#FIXED_ARRAY_NUM_ARCS_SHALLOW"/>. + /// <see cref="FST.FIXED_ARRAY_NUM_ARCS_SHALLOW"/>. /// - /// <p> + /// <para/> /// Fixed array consumes more RAM but enables binary search on the arcs /// (instead of a linear scan) on lookup by arc label. /// </summary> - /// <returns> <code>true</code> if <code>node</code> should be stored in an + /// <returns> <c>true</c> if <paramref name="node"/> should be stored in an /// expanded (array) form. /// </returns> - /// <seealso cref= #FIXED_ARRAY_NUM_ARCS_DEEP </seealso> - /// <seealso cref= Builder.UnCompiledNode#depth </seealso> + /// <seealso cref="FST.FIXED_ARRAY_NUM_ARCS_DEEP"/> + /// <seealso cref="Builder.UnCompiledNode{S}.Depth"/> private bool ShouldExpand(Builder.UnCompiledNode<T> node) { return allowArrayArcs && ((node.Depth <= FST.FIXED_ARRAY_SHALLOW_DISTANCE && node.NumArcs >= FST.FIXED_ARRAY_NUM_ARCS_SHALLOW) || node.NumArcs >= FST.FIXED_ARRAY_NUM_ARCS_DEEP); } /// <summary> - /// Returns a <seealso cref="FST.BytesReader"/> for this FST, positioned at - /// position 0. + /// Returns a <see cref="FST.BytesReader"/> for this FST, positioned at + /// position 0. /// </summary> public FST.BytesReader GetBytesReader() { @@ -1635,7 +1635,9 @@ namespace Lucene.Net.Util.Fst } */ - // Creates a packed FST + /// <summary> + /// Creates a packed FST + /// </summary> private FST(FST.INPUT_TYPE inputType, Outputs<T> outputs, int bytesPageBits) { version = FST.VERSION_CURRENT; @@ -1652,17 +1654,17 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Expert: creates an FST by packing this one. this - /// process requires substantial additional RAM (currently - /// up to ~8 bytes per node depending on - /// <code>acceptableOverheadRatio</code>), but then should - /// produce a smaller FST. + /// Expert: creates an FST by packing this one. This + /// process requires substantial additional RAM (currently + /// up to ~8 bytes per node depending on + /// <c>acceptableOverheadRatio</c>), but then should + /// produce a smaller FST. /// - /// <p>The implementation of this method uses ideas from - /// <a target="_blank" href="http://www.cs.put.poznan.pl/dweiss/site/publications/download/fsacomp.pdf";>Smaller Representation of Finite State Automata</a>, - /// which describes techniques to reduce the size of a FST. - /// However, this is not a strict implementation of the - /// algorithms described in this paper. + /// <para/>The implementation of this method uses ideas from + /// <a target="_blank" href="http://www.cs.put.poznan.pl/dweiss/site/publications/download/fsacomp.pdf";>Smaller Representation of Finite State Automata</a>, + /// which describes techniques to reduce the size of a FST. + /// However, this is not a strict implementation of the + /// algorithms described in this paper. /// </summary> internal FST<T> Pack(int minInCountDeref, int maxDerefNodes, float acceptableOverheadRatio) { @@ -2145,20 +2147,26 @@ namespace Lucene.Net.Util.Fst internal const int VERSION_CURRENT = VERSION_VINT32_TARGET; - // Never serialized; just used to represent the virtual - // final node w/ no arcs: + /// <summary> + /// Never serialized; just used to represent the virtual + /// final node w/ no arcs: + /// </summary> internal const long FINAL_END_NODE = -1; - // Never serialized; just used to represent the virtual - // non-final node w/ no arcs: + /// <summary> + /// Never serialized; just used to represent the virtual + /// non-final node w/ no arcs: + /// </summary> internal const long NON_FINAL_END_NODE = 0; /// <summary> /// If arc has this label then that arc is final/accepted </summary> public static readonly int END_LABEL = -1; - // returns true if the node at this address has any - // outgoing arcs + /// <summary> + /// returns <c>true</c> if the node at this address has any + /// outgoing arcs + /// </summary> public static bool TargetHasArcs<T>(Arc<T> arc) { return arc.Target > 0; @@ -2201,7 +2209,7 @@ namespace Lucene.Net.Util.Fst public abstract long Position { get; set; } /// <summary> - /// Returns true if this reader uses reversed bytes + /// Returns <c>true</c> if this reader uses reversed bytes /// under-the-hood. /// </summary> /// <returns></returns> @@ -2229,8 +2237,10 @@ namespace Lucene.Net.Util.Fst public T Output { get; set; } - // From node (ord or address); currently only used when - // building an FST w/ willPackFST=true: + /// <summary> + /// From node (ord or address); currently only used when + /// building an FST w/ willPackFST=true: + /// </summary> internal long Node { get; set; } /// <summary> @@ -2242,10 +2252,14 @@ namespace Lucene.Net.Util.Fst public T NextFinalOutput { get; set; } - // address (into the byte[]), or ord/address if label == END_LABEL + /// <summary> + /// address (into the byte[]), or ord/address if label == END_LABEL + /// </summary> internal long NextArc { get; set; } - // This is non-zero if current arcs are fixed array: + /// <summary> + /// This is non-zero if current arcs are fixed array: + /// </summary> internal long PosArcsStart { get; set; } internal int BytesPerArc { get; set; } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/FSTEnum.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/FSTEnum.cs b/src/Lucene.Net.Core/Util/Fst/FSTEnum.cs index 56ac818..a378b39 100644 --- a/src/Lucene.Net.Core/Util/Fst/FSTEnum.cs +++ b/src/Lucene.Net.Core/Util/Fst/FSTEnum.cs @@ -21,8 +21,8 @@ namespace Lucene.Net.Util.Fst */ /// <summary> - /// Can next() and advance() through the terms in an FST - /// + /// Can Next() and Advance() through the terms in an FST + /// <para/> /// @lucene.experimental /// </summary> public abstract class FSTEnum<T> // LUCENENET NOTE: changed from internal to public because has public subclasses @@ -43,8 +43,8 @@ namespace Lucene.Net.Util.Fst /// <summary> /// doFloor controls the behavior of advance: if it's true - /// doFloor is true, advance positions to the biggest - /// term before target. + /// doFloor is true, advance positions to the biggest + /// term before target. /// </summary> protected FSTEnum(FST<T> fst) { @@ -63,7 +63,7 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Rewinds enum state to match the shared prefix between - /// current term and target term + /// current term and target term /// </summary> protected void RewindPrefix() { @@ -132,7 +132,7 @@ namespace Lucene.Net.Util.Fst // SEEK_END)? saves the eq check above? /// <summary> - /// Seeks to smallest term that's >= target. </summary> + /// Seeks to smallest term that's >= target. </summary> protected virtual void DoSeekCeil() { //System.out.println(" advance len=" + target.length + " curlen=" + current.length); @@ -303,7 +303,7 @@ namespace Lucene.Net.Util.Fst // TODO: should we return a status here (SEEK_FOUND / SEEK_NOT_FOUND / // SEEK_END)? saves the eq check above? /// <summary> - /// Seeks to largest term that's <= target. </summary> + /// Seeks to largest term that's <= target. </summary> protected virtual void DoSeekFloor() { // TODO: possibly caller could/should provide common @@ -563,8 +563,10 @@ namespace Lucene.Net.Util.Fst } } - // Appends current arc, and then recurses from its target, - // appending first arc all the way to the final node + /// <summary> + /// Appends current arc, and then recurses from its target, + /// appending first arc all the way to the final node + /// </summary> private void PushFirst() { FST.Arc<T> arc = m_arcs[m_upto]; @@ -588,8 +590,10 @@ namespace Lucene.Net.Util.Fst } } - // Recurses from current arc, appending last arc all the - // way to the first final node + /// <summary> + /// Recurses from current arc, appending last arc all the + /// way to the first final node + /// </summary> private void PushLast() { FST.Arc<T> arc = m_arcs[m_upto]; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/ForwardBytesReader.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/ForwardBytesReader.cs b/src/Lucene.Net.Core/Util/Fst/ForwardBytesReader.cs index 694f438..5d806b2 100644 --- a/src/Lucene.Net.Core/Util/Fst/ForwardBytesReader.cs +++ b/src/Lucene.Net.Core/Util/Fst/ForwardBytesReader.cs @@ -23,7 +23,7 @@ namespace Lucene.Net.Util.Fst // add a .skipBytes to DataInput.. hmm and .setPosition /// <summary> - /// Reads from a single byte[]. </summary> + /// Reads from a single <see cref="T:byte[]"/>. </summary> internal sealed class ForwardBytesReader : FST.BytesReader { private readonly byte[] bytes; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/IntSequenceOutputs.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/IntSequenceOutputs.cs b/src/Lucene.Net.Core/Util/Fst/IntSequenceOutputs.cs index 1f586ba..76509b4 100644 --- a/src/Lucene.Net.Core/Util/Fst/IntSequenceOutputs.cs +++ b/src/Lucene.Net.Core/Util/Fst/IntSequenceOutputs.cs @@ -25,10 +25,10 @@ namespace Lucene.Net.Util.Fst /// <summary> /// An FST <see cref="Outputs{T}"/> implementation where each output - /// is a sequence of ints. + /// is a sequence of <see cref="int"/>s. /// <para/> /// NOTE: This was IntSequenceOutputs in Lucene - /// + /// <para/> /// @lucene.experimental /// </summary> public sealed class Int32SequenceOutputs : Outputs<Int32sRef> http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/IntsRefFSTEnum.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/IntsRefFSTEnum.cs b/src/Lucene.Net.Core/Util/Fst/IntsRefFSTEnum.cs index 9fea57c..6ede82d 100644 --- a/src/Lucene.Net.Core/Util/Fst/IntsRefFSTEnum.cs +++ b/src/Lucene.Net.Core/Util/Fst/IntsRefFSTEnum.cs @@ -20,11 +20,11 @@ namespace Lucene.Net.Util.Fst */ /// <summary> - /// Enumerates all input (IntsRef) + output pairs in an + /// Enumerates all input (<see cref="Int32sRef"/>) + output pairs in an /// FST. /// <para/> /// NOTE: This was IntsRefFSTEnum{T} in Lucene - /// + /// <para/> /// @lucene.experimental /// </summary> public sealed class Int32sRefFSTEnum<T> : FSTEnum<T> @@ -37,8 +37,8 @@ namespace Lucene.Net.Util.Fst /// <summary> /// doFloor controls the behavior of advance: if it's true - /// doFloor is true, advance positions to the biggest - /// term before target. + /// doFloor is true, advance positions to the biggest + /// term before target. /// </summary> public Int32sRefFSTEnum(FST<T> fst) : base(fst) @@ -60,7 +60,7 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Seeks to smallest term that's >= target. </summary> + /// Seeks to smallest term that's >= target. </summary> public Int32sRefFSTEnum.InputOutput<T> SeekCeil(Int32sRef target) { this.target = target; @@ -70,7 +70,7 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Seeks to biggest term that's <= target. </summary> + /// Seeks to biggest term that's <= target. </summary> public Int32sRefFSTEnum.InputOutput<T> SeekFloor(Int32sRef target) { this.target = target; @@ -80,10 +80,10 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Seeks to exactly this term, returning null if the term - /// doesn't exist. this is faster than using {@link - /// #seekFloor} or <seealso cref="#seekCeil"/> because it - /// short-circuits as soon the match is not found. + /// Seeks to exactly this term, returning <c>null</c> if the term + /// doesn't exist. This is faster than using + /// <see cref="SeekFloor"/> or <see cref="SeekCeil"/> because it + /// short-circuits as soon the match is not found. /// </summary> public Int32sRefFSTEnum.InputOutput<T> SeekExact(Int32sRef target) { @@ -161,7 +161,7 @@ namespace Lucene.Net.Util.Fst { } /// <summary> - /// Holds a single input (IntsRef) + output pair. </summary> + /// Holds a single input (<see cref="Int32sRef"/>) + output pair. </summary> public class InputOutput<T> { public Int32sRef Input { get; set; } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/NoOutputs.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/NoOutputs.cs b/src/Lucene.Net.Core/Util/Fst/NoOutputs.cs index 81a9946..ec36431 100644 --- a/src/Lucene.Net.Core/Util/Fst/NoOutputs.cs +++ b/src/Lucene.Net.Core/Util/Fst/NoOutputs.cs @@ -23,9 +23,9 @@ namespace Lucene.Net.Util.Fst using DataOutput = Lucene.Net.Store.DataOutput; /// <summary> - /// A null FST <seealso cref="Outputs"/> implementation; use this if + /// A null FST <see cref="Outputs{T}"/> implementation; use this if /// you just want to build an FSA. - /// + /// <para/> /// @lucene.experimental /// </summary> public sealed class NoOutputs : Outputs<object> @@ -38,8 +38,10 @@ namespace Lucene.Net.Util.Fst { } - // NodeHash calls hashCode for this output; we fix this - // so we get deterministic hashing. + /// <summary> + /// NodeHash calls hashCode for this output; we fix this + /// so we get deterministic hashing. + /// </summary> public override int GetHashCode() { return 42; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/NodeHash.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/NodeHash.cs b/src/Lucene.Net.Core/Util/Fst/NodeHash.cs index 67dc54e..ed20ea2 100644 --- a/src/Lucene.Net.Core/Util/Fst/NodeHash.cs +++ b/src/Lucene.Net.Core/Util/Fst/NodeHash.cs @@ -23,7 +23,9 @@ namespace Lucene.Net.Util.Fst using PackedInt32s = Lucene.Net.Util.Packed.PackedInt32s; using PagedGrowableWriter = Lucene.Net.Util.Packed.PagedGrowableWriter; - // Used to dedup states (lookup already-frozen states) + /// <summary> + /// Used to dedup states (lookup already-frozen states) + /// </summary> internal sealed class NodeHash<T> { private PagedGrowableWriter table; @@ -73,8 +75,10 @@ namespace Lucene.Net.Util.Fst return false; } - // hash code for an unfrozen node. this must be identical - // to the frozen case (below)!! + /// <summary> + /// hash code for an unfrozen node. this must be identical + /// to the frozen case (below)!! + /// </summary> private long Hash(Builder.UnCompiledNode<T> node) { const int PRIME = 31; @@ -98,7 +102,9 @@ namespace Lucene.Net.Util.Fst return h & long.MaxValue; } - // hash code for a frozen node + /// <summary> + /// hash code for a frozen node + /// </summary> private long Hash(long node) { const int PRIME = 31; @@ -162,7 +168,9 @@ namespace Lucene.Net.Util.Fst } } - // called only by rehash + /// <summary> + /// called only by rehash + /// </summary> private void AddNew(long address) { long pos = Hash(address) & mask; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/Outputs.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/Outputs.cs b/src/Lucene.Net.Core/Util/Fst/Outputs.cs index d344b57..4b5677b 100644 --- a/src/Lucene.Net.Core/Util/Fst/Outputs.cs +++ b/src/Lucene.Net.Core/Util/Fst/Outputs.cs @@ -24,9 +24,9 @@ namespace Lucene.Net.Util.Fst /// Represents the outputs for an FST, providing the basic /// 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 - /// #getNoOutput}.</p> + /// <para>Note that any operation that returns NO_OUTPUT must + /// return the same singleton object from + /// <see cref="NoOutput"/>.</para> /// /// @lucene.experimental /// </summary> @@ -50,13 +50,13 @@ namespace Lucene.Net.Util.Fst public abstract T Add(T prefix, T output); /// <summary> - /// Encode an output value into a <seealso cref="DataOutput"/>. </summary> + /// Encode an output value into a <see cref="DataOutput"/>. </summary> public abstract void Write(T output, DataOutput @out); /// <summary> - /// Encode an final node output value into a {@link - /// DataOutput}. By default this just calls {@link #write(Object, - /// DataOutput)}. + /// Encode an final node output value into a + /// <see cref="DataOutput"/>. By default this just calls + /// <see cref="Write(T, DataOutput)"/>. /// </summary> public virtual void WriteFinalOutput(T output, DataOutput @out) { @@ -64,15 +64,15 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Decode an output value previously written with {@link - /// #write(Object, DataOutput)}. + /// Decode an output value previously written with + /// <see cref="Write(T, DataOutput)"/>. /// </summary> public abstract T Read(DataInput @in); /// <summary> - /// Decode an output value previously written with {@link - /// #writeFinalOutput(Object, DataOutput)}. By default this - /// just calls <seealso cref="#read(DataInput)"/>. + /// Decode an output value previously written with + /// <see cref="WriteFinalOutput(T, DataOutput)"/>. By default this + /// just calls <see cref="Read(DataInput)"/>. /// </summary> public virtual T ReadFinalOutput(DataInput @in) { @@ -81,8 +81,8 @@ namespace Lucene.Net.Util.Fst /// <summary> /// NOTE: this output is compared with == so you must - /// ensure that all methods return the single object if - /// it's really no output + /// ensure that all methods return the single object if + /// it's really no output /// </summary> public abstract T NoOutput { get; } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/PairOutputs.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/PairOutputs.cs b/src/Lucene.Net.Core/Util/Fst/PairOutputs.cs index 5f52d71..7ba14ac 100644 --- a/src/Lucene.Net.Core/Util/Fst/PairOutputs.cs +++ b/src/Lucene.Net.Core/Util/Fst/PairOutputs.cs @@ -24,7 +24,7 @@ namespace Lucene.Net.Util.Fst /// <summary> /// An FST <see cref="Outputs{T}"/> implementation, holding two other outputs. - /// + /// <para/> /// @lucene.experimental /// </summary> public class PairOutputs<A, B> : Outputs<PairOutputs<A, B>.Pair> @@ -78,7 +78,7 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Create a new Pair </summary> + /// Create a new <see cref="Pair"/> </summary> public virtual Pair NewPair(A a, B b) { if (a.Equals(outputs1.NoOutput)) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/PositiveIntOutputs.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/PositiveIntOutputs.cs b/src/Lucene.Net.Core/Util/Fst/PositiveIntOutputs.cs index 4350dc9..8897054 100644 --- a/src/Lucene.Net.Core/Util/Fst/PositiveIntOutputs.cs +++ b/src/Lucene.Net.Core/Util/Fst/PositiveIntOutputs.cs @@ -24,8 +24,8 @@ namespace Lucene.Net.Util.Fst using DataOutput = Lucene.Net.Store.DataOutput; /// <summary> - /// An FST <seealso cref="Outputs{T}"/> implementation where each output - /// is a non-negative long value. + /// An FST <see cref="Outputs{T}"/> implementation where each output + /// is a non-negative <see cref="long?"/> value. /// <para/> /// NOTE: This was PositiveIntOutputs in Lucene /// http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/ReverseBytesReader.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/ReverseBytesReader.cs b/src/Lucene.Net.Core/Util/Fst/ReverseBytesReader.cs index 3266aad..c64387c 100644 --- a/src/Lucene.Net.Core/Util/Fst/ReverseBytesReader.cs +++ b/src/Lucene.Net.Core/Util/Fst/ReverseBytesReader.cs @@ -18,7 +18,7 @@ namespace Lucene.Net.Util.Fst */ /// <summary> - /// Reads in reverse from a single byte[]. </summary> + /// Reads in reverse from a single <see cref="T:byte[]"/>. </summary> internal sealed class ReverseBytesReader : FST.BytesReader { private readonly byte[] bytes; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/3724588b/src/Lucene.Net.Core/Util/Fst/Util.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Util/Fst/Util.cs b/src/Lucene.Net.Core/Util/Fst/Util.cs index 44bd4bc..b206948 100644 --- a/src/Lucene.Net.Core/Util/Fst/Util.cs +++ b/src/Lucene.Net.Core/Util/Fst/Util.cs @@ -26,7 +26,7 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Static helper methods. - /// + /// <para/> /// @lucene.experimental /// </summary> public sealed class Util // LUCENENET TODO: Fix naming conflict with containing namespace @@ -36,8 +36,8 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Looks up the output for this input, or null if the - /// input is not accepted. + /// Looks up the output for this input, or <c>null</c> if the + /// input is not accepted. /// </summary> public static T Get<T>(FST<T> fst, Int32sRef input) { @@ -70,8 +70,8 @@ namespace Lucene.Net.Util.Fst // TODO: maybe a CharsRef version for BYTE2 /// <summary> - /// Looks up the output for this input, or null if the - /// input is not accepted + /// Looks up the output for this input, or <c>null</c> if the + /// input is not accepted /// </summary> public static T Get<T>(FST<T> fst, BytesRef input) { @@ -105,17 +105,17 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Reverse lookup (lookup by output instead of by input), - /// in the special case when your FSTs outputs are - /// strictly ascending. this locates the input/output - /// pair where the output is equal to the target, and will - /// return null if that output does not exist. + /// in the special case when your FSTs outputs are + /// strictly ascending. This locates the input/output + /// pair where the output is equal to the target, and will + /// return <c>null</c> if that output does not exist. /// - /// <p>NOTE: this only works with {@code FST<Long>}, only - /// works when the outputs are ascending in order with - /// the inputs. - /// For example, simple ordinals (0, 1, - /// 2, ...), or file offets (when appending to a file) - /// fit this. + /// <para/>NOTE: this only works with <see cref="T:FST{long?}"/>, only + /// works when the outputs are ascending in order with + /// the inputs. + /// For example, simple ordinals (0, 1, + /// 2, ...), or file offets (when appending to a file) + /// fit this. /// </summary> public static Int32sRef GetByOutput(FST<long?> fst, long targetOutput) { @@ -132,8 +132,8 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Expert: like <seealso cref="Util#getByOutput(FST, long)"/> except reusing - /// BytesReader, initial and scratch Arc, and result. + /// Expert: like <see cref="Util.GetByOutput(FST{long?}, long)"/> except reusing + /// <see cref="FST.BytesReader"/>, initial and scratch Arc, and result. /// </summary> public static Int32sRef GetByOutput(FST<long?> fst, long targetOutput, FST.BytesReader @in, FST.Arc<long?> arc, FST.Arc<long?> scratchArc, Int32sRef result) { @@ -294,8 +294,8 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Represents a path in TopNSearcher. - /// - /// @lucene.experimental + /// <para/> + /// @lucene.experimental /// </summary> public class FSTPath<T> { @@ -320,7 +320,7 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Compares first by the provided comparer, and then - /// tie breaks by path.input. + /// tie breaks by <see cref="FSTPath{T}.Input"/>. /// </summary> private class TieBreakByInputComparer<T> : IComparer<FSTPath<T>> { @@ -347,7 +347,7 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Utility class to find top N shortest paths from start - /// point(s). + /// point(s). /// </summary> public class TopNSearcher<T> { @@ -366,7 +366,7 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Creates an unbounded TopNSearcher </summary> - /// <param name="fst"> the <seealso cref="Lucene.Net.Util.Fst.FST"/> to search on </param> + /// <param name="fst"> the <see cref="Lucene.Net.Util.Fst.FST{T}"/> to search on </param> /// <param name="topN"> the number of top scoring entries to retrieve </param> /// <param name="maxQueueDepth"> the maximum size of the queue of possible top entries </param> /// <param name="comparer"> the comparer to select the top N </param> @@ -381,7 +381,9 @@ namespace Lucene.Net.Util.Fst queue = new SortedSet<FSTPath<T>>(new TieBreakByInputComparer<T>(comparer)); } - // If back plus this arc is competitive then add to queue: + /// <summary> + /// If back plus this arc is competitive then add to queue: + /// </summary> protected virtual void AddIfCompetitive(FSTPath<T> path) { Debug.Assert(queue != null); @@ -447,7 +449,7 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Adds all leaving arcs, including 'finished' arc, if - /// the node is final, from this node into the queue. + /// the node is final, from this node into the queue. /// </summary> public virtual void AddStartPaths(FST.Arc<T> node, T startOutput, bool allowEmptyString, Int32sRef input) { @@ -641,8 +643,8 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Holds a single input (IntsRef) + output, returned by - /// <seealso cref="#shortestPaths shortestPaths()"/>. + /// Holds a single input (<see cref="Int32sRef"/>) + output, returned by + /// <see cref="ShortestPaths"/>. /// </summary> public sealed class Result<T> { @@ -657,14 +659,14 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Holds the results for a top N search using <seealso cref="TopNSearcher"/> + /// Holds the results for a top N search using <see cref="TopNSearcher{T}"/> /// </summary> public sealed class TopResults<T> : IEnumerable<Result<T>> { /// <summary> - /// <code>true</code> iff this is a complete result ie. if + /// <c>true</c> iff this is a complete result ie. if /// the specified queue size was large enough to find the complete list of results. this might - /// be <code>false</code> if the <seealso cref="TopNSearcher"/> rejected too many results. + /// be <c>false</c> if the <see cref="TopNSearcher{T}"/> rejected too many results. /// </summary> public bool IsComplete { get; private set; } @@ -692,7 +694,7 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Starting from node, find the top N min cost - /// completions to a final node. + /// completions to a final node. /// </summary> public static TopResults<T> ShortestPaths<T>(FST<T> fst, FST.Arc<T> fromNode, T startOutput, IComparer<T> comparer, int topN, bool allowEmptyString) { @@ -707,36 +709,38 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Dumps an <seealso cref="FST"/> to a GraphViz's <code>dot</code> language description + /// Dumps an <see cref="FST{T}"/> to a GraphViz's <c>dot</c> language description /// for visualization. Example of use: /// - /// <pre class="prettyprint"> - /// PrintWriter pw = new PrintWriter("out.dot"); - /// Util.toDot(fst, pw, true, true); - /// pw.Dispose(); - /// </pre> + /// <code> + /// using (TextWriter sw = new StreamWriter("out.dot")) + /// { + /// Util.ToDot(fst, sw, true, true); + /// } + /// </code> /// /// and then, from command line: /// - /// <pre> + /// <code> /// dot -Tpng -o out.png out.dot - /// </pre> + /// </code> /// - /// <p> + /// <para/> /// Note: larger FSTs (a few thousand nodes) won't even - /// render, don't bother. If the FST is > 2.1 GB in size + /// render, don't bother. If the FST is > 2.1 GB in size /// then this method will throw strange exceptions. + /// <para/> + /// See also <a href="http://www.graphviz.org/";>http://www.graphviz.org/</a>. /// </summary> /// <param name="sameRank"> - /// If <code>true</code>, the resulting <code>dot</code> file will try - /// to order states in layers of breadth-first traversal. this may + /// If <c>true</c>, the resulting <c>dot</c> file will try + /// to order states in layers of breadth-first traversal. This may /// mess up arcs, but makes the output FST's structure a bit clearer. /// </param> /// <param name="labelStates"> - /// If <code>true</code> states will have labels equal to their offsets in their + /// If <c>true</c> states will have labels equal to their offsets in their /// binary format. Expands the graph considerably. /// </param> - /// <seealso cref= "http://www.graphviz.org/"; </seealso> public static void ToDot<T>(FST<T> fst, TextWriter @out, bool sameRank, bool labelStates) { const string expandedNodeColor = "blue"; @@ -948,7 +952,7 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Emit a single state in the <code>dot</code> language. + /// Emit a single state in the <c>dot</c> language. /// </summary> private static void EmitDotState(TextWriter @out, string name, string shape, string color, string label) { @@ -975,8 +979,8 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Just maps each UTF16 unit (char) to the ints in an - /// IntsRef. + /// Just maps each UTF16 unit (char) to the <see cref="int"/>s in an + /// <see cref="Int32sRef"/>. /// </summary> public static Int32sRef ToUTF16(string s, Int32sRef scratch) { @@ -993,8 +997,8 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Decodes the Unicode codepoints from the provided - /// CharSequence and places them in the provided scratch - /// IntsRef, which must not be null, returning it. + /// <see cref="ICharSequence"/> and places them in the provided scratch + /// <see cref="Int32sRef"/>, which must not be <c>null</c>, returning it. /// </summary> public static Int32sRef ToUTF32(string s, Int32sRef scratch) { @@ -1015,8 +1019,8 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Decodes the Unicode codepoints from the provided - /// char[] and places them in the provided scratch - /// IntsRef, which must not be null, returning it. + /// <see cref="T:char[]"/> and places them in the provided scratch + /// <see cref="Int32sRef"/>, which must not be <c>null</c>, returning it. /// </summary> public static Int32sRef ToUTF32(char[] s, int offset, int length, Int32sRef scratch) { @@ -1036,8 +1040,8 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Just takes unsigned byte values from the BytesRef and - /// converts into an IntsRef. + /// Just takes unsigned byte values from the <see cref="BytesRef"/> and + /// converts into an <see cref="Int32sRef"/>. /// <para/> /// NOTE: This was toIntsRef() in Lucene /// </summary> @@ -1053,8 +1057,8 @@ namespace Lucene.Net.Util.Fst } /// <summary> - /// Just converts IntsRef to BytesRef; you must ensure the - /// int values fit into a byte. + /// Just converts <see cref="Int32sRef"/> to <see cref="BytesRef"/>; you must ensure the + /// <see cref="int"/> values fit into a <see cref="byte"/>. /// </summary> public static BytesRef ToBytesRef(Int32sRef input, BytesRef scratch) { @@ -1082,13 +1086,13 @@ namespace Lucene.Net.Util.Fst /// <summary> /// Reads the first arc greater or equal that the given label into the provided - /// arc in place and returns it iff found, otherwise return <code>null</code>. + /// arc in place and returns it iff found, otherwise return <c>null</c>. /// </summary> /// <param name="label"> the label to ceil on </param> /// <param name="fst"> the fst to operate on </param> /// <param name="follow"> the arc to follow reading the label from </param> /// <param name="arc"> the arc to read into in place </param> - /// <param name="in"> the fst's <seealso cref="BytesReader"/> </param> + /// <param name="in"> the fst's <see cref="FST.BytesReader"/> </param> public static FST.Arc<T> ReadCeilArc<T>(int label, FST<T> fst, FST.Arc<T> follow, FST.Arc<T> arc, FST.BytesReader @in) { // TODO maybe this is a useful in the FST class - we could simplify some other code like FSTEnum?
