http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/NumericUtils.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/NumericUtils.cs b/src/Lucene.Net/Util/NumericUtils.cs index 5cc67fd..6c96e16 100644 --- a/src/Lucene.Net/Util/NumericUtils.cs +++ b/src/Lucene.Net/Util/NumericUtils.cs @@ -24,38 +24,39 @@ namespace Lucene.Net.Util using TermsEnum = Lucene.Net.Index.TermsEnum; /// <summary> - /// this is a helper class to generate prefix-encoded representations for numerical values + /// This is a helper class to generate prefix-encoded representations for numerical values /// and supplies converters to represent float/double values as sortable integers/longs. /// - /// <p>To quickly execute range queries in Apache Lucene, a range is divided recursively + /// <para/>To quickly execute range queries in Apache Lucene, a range is divided recursively /// into multiple intervals for searching: The center of the range is searched only with /// the lowest possible precision in the trie, while the boundaries are matched /// more exactly. this reduces the number of terms dramatically. /// - /// <p>this class generates terms to achieve this: First the numerical integer values need to + /// <para/>This class generates terms to achieve this: First the numerical integer values need to /// be converted to bytes. For that integer values (32 bit or 64 bit) are made unsigned /// and the bits are converted to ASCII chars with each 7 bit. The resulting byte[] is /// sortable like the original integer value (even using UTF-8 sort order). Each value is also - /// prefixed (in the first char) by the <code>shift</code> value (number of bits removed) used + /// prefixed (in the first char) by the <c>shift</c> value (number of bits removed) used /// during encoding. /// - /// <p>To also index floating point numbers, this class supplies two methods to convert them - /// to integer values by changing their bit layout: <seealso cref="#doubleToSortableLong"/>, - /// <seealso cref="#floatToSortableInt"/>. You will have no precision loss by + /// <para/>To also index floating point numbers, this class supplies two methods to convert them + /// to integer values by changing their bit layout: <see cref="DoubleToSortableInt64(double)"/>, + /// <see cref="SingleToSortableInt32(float)"/>. You will have no precision loss by /// converting floating point numbers to integers and back (only that the integer form - /// is not usable). Other data types like dates can easily converted to longs or ints (e.g. - /// date to long: <seealso cref="java.util.Date#getTime"/>). + /// is not usable). Other data types like dates can easily converted to <see cref="long"/>s or <see cref="int"/>s (e.g. + /// date to long: <see cref="DateTime.Ticks"/>). /// - /// <p>For easy usage, the trie algorithm is implemented for indexing inside - /// <seealso cref="NumericTokenStream"/> that can index <code>int</code>, <code>long</code>, - /// <code>float</code>, and <code>double</code>. For querying, - /// <seealso cref="NumericRangeQuery"/> and <seealso cref="NumericRangeFilter"/> implement the query part + /// <para/>For easy usage, the trie algorithm is implemented for indexing inside + /// <see cref="Analysis.NumericTokenStream"/> that can index <see cref="int"/>, <see cref="long"/>, + /// <see cref="float"/>, and <see cref="double"/>. For querying, + /// <see cref="Search.NumericRangeQuery"/> and <see cref="Search.NumericRangeFilter"/> implement the query part /// for the same data types. /// - /// <p>this class can also be used, to generate lexicographically sortable (according to - /// <seealso cref="BytesRef#getUTF8SortedAsUTF16Comparer()"/>) representations of numeric data + /// <para/>This class can also be used, to generate lexicographically sortable (according to + /// <see cref="BytesRef.UTF8SortedAsUTF16Comparer"/>) representations of numeric data /// types for other usages (e.g. sorting). /// + /// <para/> /// @lucene.internal /// @since 2.9, API changed non backwards-compliant in 4.0 /// </summary> @@ -66,10 +67,10 @@ namespace Lucene.Net.Util } /// <summary> - /// The default precision step used by <seealso cref="IntField"/>, - /// <seealso cref="FloatField"/>, <seealso cref="LongField"/>, {@link - /// DoubleField}, <seealso cref="NumericTokenStream"/>, {@link - /// NumericRangeQuery}, and <seealso cref="NumericRangeFilter"/>. + /// The default precision step used by <see cref="Documents.Int32Field"/>, + /// <see cref="Documents.SingleField"/>, <see cref="Documents.Int64Field"/>, + /// <see cref="Documents.DoubleField"/>, <see cref="Analysis.NumericTokenStream"/>, + /// <see cref="Search.NumericRangeQuery"/>, and <see cref="Search.NumericRangeFilter"/>. /// </summary> public const int PRECISION_STEP_DEFAULT = 4; @@ -82,7 +83,7 @@ namespace Lucene.Net.Util public const char SHIFT_START_INT64 = (char)0x20; /// <summary> - /// The maximum term length (used for <code>byte[]</code> buffer size) + /// The maximum term length (used for <see cref="T:byte[]"/> buffer size) /// for encoding <see cref="long"/> values. /// <para/> /// NOTE: This was BUF_SIZE_LONG in Lucene @@ -92,7 +93,7 @@ namespace Lucene.Net.Util /// <summary> /// Integers are stored at lower precision by shifting off lower bits. The shift count is - /// stored as <code>SHIFT_START_INT32+shift</code> in the first byte + /// stored as <c>SHIFT_START_INT32+shift</c> in the first byte /// <para/> /// NOTE: This was SHIFT_START_INT in Lucene /// </summary> @@ -108,45 +109,45 @@ namespace Lucene.Net.Util public const int BUF_SIZE_INT32 = 31 / 7 + 2; /// <summary> - /// Returns prefix coded bits after reducing the precision by <code>shift</code> bits. - /// this is method is used by <seealso cref="NumericTokenStream"/>. - /// After encoding, {@code bytes.offset} will always be 0. + /// Returns prefix coded bits after reducing the precision by <paramref name="shift"/> bits. + /// This is method is used by <see cref="Analysis.NumericTokenStream"/>. + /// After encoding, <c>bytes.Offset</c> will always be 0. /// <para/> /// NOTE: This was longToPrefixCoded() in Lucene /// </summary> - /// <param name="val"> the numeric value </param> - /// <param name="shift"> how many bits to strip from the right </param> - /// <param name="bytes"> will contain the encoded value </param> + /// <param name="val"> The numeric value </param> + /// <param name="shift"> How many bits to strip from the right </param> + /// <param name="bytes"> Will contain the encoded value </param> public static void Int64ToPrefixCoded(long val, int shift, BytesRef bytes) { Int64ToPrefixCodedBytes(val, shift, bytes); } /// <summary> - /// Returns prefix coded bits after reducing the precision by <code>shift</code> bits. - /// this is method is used by <seealso cref="NumericTokenStream"/>. - /// After encoding, {@code bytes.offset} will always be 0. + /// Returns prefix coded bits after reducing the precision by <paramref name="shift"/> bits. + /// This is method is used by <see cref="Analysis.NumericTokenStream"/>. + /// After encoding, <c>bytes.Offset</c> will always be 0. /// <para/> /// NOTE: This was intToPrefixCoded() in Lucene /// </summary> - /// <param name="val"> the numeric value </param> - /// <param name="shift"> how many bits to strip from the right </param> - /// <param name="bytes"> will contain the encoded value </param> + /// <param name="val"> The numeric value </param> + /// <param name="shift"> How many bits to strip from the right </param> + /// <param name="bytes"> Will contain the encoded value </param> public static void Int32ToPrefixCoded(int val, int shift, BytesRef bytes) { Int32ToPrefixCodedBytes(val, shift, bytes); } /// <summary> - /// Returns prefix coded bits after reducing the precision by <code>shift</code> bits. - /// this is method is used by <seealso cref="NumericTokenStream"/>. - /// After encoding, {@code bytes.offset} will always be 0. + /// Returns prefix coded bits after reducing the precision by <paramref name="shift"/> bits. + /// This is method is used by <see cref="Analysis.NumericTokenStream"/>. + /// After encoding, <c>bytes.Offset</c> will always be 0. /// <para/> /// NOTE: This was longToPrefixCodedBytes() in Lucene /// </summary> - /// <param name="val"> the numeric value </param> - /// <param name="shift"> how many bits to strip from the right </param> - /// <param name="bytes"> will contain the encoded value </param> + /// <param name="val"> The numeric value </param> + /// <param name="shift"> How many bits to strip from the right </param> + /// <param name="bytes"> Will contain the encoded value </param> public static void Int64ToPrefixCodedBytes(long val, int shift, BytesRef bytes) { if ((shift & ~0x3f) != 0) // ensure shift is 0..63 @@ -173,15 +174,15 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns prefix coded bits after reducing the precision by <code>shift</code> bits. - /// this is method is used by <seealso cref="NumericTokenStream"/>. - /// After encoding, {@code bytes.offset} will always be 0. + /// Returns prefix coded bits after reducing the precision by <paramref name="shift"/> bits. + /// This is method is used by <see cref="Analysis.NumericTokenStream"/>. + /// After encoding, <c>bytes.Offset</c> will always be 0. /// <para/> /// NOTE: This was intToPrefixCodedBytes() in Lucene /// </summary> - /// <param name="val"> the numeric value </param> - /// <param name="shift"> how many bits to strip from the right </param> - /// <param name="bytes"> will contain the encoded value </param> + /// <param name="val"> The numeric value </param> + /// <param name="shift"> How many bits to strip from the right </param> + /// <param name="bytes"> Will contain the encoded value </param> public static void Int32ToPrefixCodedBytes(int val, int shift, BytesRef bytes) { if ((shift & ~0x1f) != 0) // ensure shift is 0..31 @@ -208,11 +209,11 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns the shift value from a prefix encoded {@code long}. + /// Returns the shift value from a prefix encoded <see cref="long"/>. /// <para/> /// NOTE: This was getPrefixCodedLongShift() in Lucene /// </summary> - /// <exception cref="NumberFormatException"> if the supplied <seealso cref="BytesRef"/> is + /// <exception cref="FormatException"> if the supplied <see cref="BytesRef"/> is /// not correctly prefix encoded. </exception> public static int GetPrefixCodedInt64Shift(BytesRef val) { @@ -225,11 +226,11 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns the shift value from a prefix encoded {@code int}. + /// Returns the shift value from a prefix encoded <see cref="int"/>. /// <para/> /// NOTE: This was getPrefixCodedIntShift() in Lucene /// </summary> - /// <exception cref="NumberFormatException"> if the supplied <seealso cref="BytesRef"/> is + /// <exception cref="FormatException"> if the supplied <see cref="BytesRef"/> is /// not correctly prefix encoded. </exception> public static int GetPrefixCodedInt32Shift(BytesRef val) { @@ -242,15 +243,15 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns a long from prefixCoded bytes. + /// Returns a <see cref="long"/> from prefixCoded bytes. /// Rightmost bits will be zero for lower precision codes. - /// this method can be used to decode a term's value. + /// This method can be used to decode a term's value. /// <para/> /// NOTE: This was prefixCodedToLong() in Lucene /// </summary> - /// <exception cref="NumberFormatException"> if the supplied <seealso cref="BytesRef"/> is + /// <exception cref="FormatException"> if the supplied <see cref="BytesRef"/> is /// not correctly prefix encoded. </exception> - /// <seealso cref= #longToPrefixCodedBytes </seealso> + /// <seealso cref="Int64ToPrefixCodedBytes(long, int, BytesRef)"/> public static long PrefixCodedToInt64(BytesRef val) { long sortableBits = 0L; @@ -268,15 +269,15 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns an int from prefixCoded bytes. + /// Returns an <see cref="int"/> from prefixCoded bytes. /// Rightmost bits will be zero for lower precision codes. - /// this method can be used to decode a term's value. + /// This method can be used to decode a term's value. /// <para/> /// NOTE: This was prefixCodedToInt() in Lucene /// </summary> - /// <exception cref="NumberFormatException"> if the supplied <seealso cref="BytesRef"/> is + /// <exception cref="FormatException"> if the supplied <see cref="BytesRef"/> is /// not correctly prefix encoded. </exception> - /// <seealso cref= #intToPrefixCodedBytes </seealso> + /// <seealso cref="Int32ToPrefixCodedBytes(int, int, BytesRef)"/> public static int PrefixCodedToInt32(BytesRef val) { long sortableBits = 0; @@ -294,16 +295,16 @@ namespace Lucene.Net.Util } /// <summary> - /// Converts a <code>double</code> value to a sortable signed <code>long</code>. + /// Converts a <see cref="double"/> value to a sortable signed <see cref="long"/>. /// The value is converted by getting their IEEE 754 floating-point "double format" - /// bit layout and then some bits are swapped, to be able to compare the result as long. - /// By this the precision is not reduced, but the value can easily used as a long. - /// The sort order (including <seealso cref="Double#NaN"/>) is defined by - /// <seealso cref="Double#compareTo"/>; {@code NaN} is greater than positive infinity. + /// bit layout and then some bits are swapped, to be able to compare the result as <see cref="long"/>. + /// By this the precision is not reduced, but the value can easily used as a <see cref="long"/>. + /// The sort order (including <see cref="double.NaN"/>) is defined by + /// <see cref="double.CompareTo(double)"/>; <c>NaN</c> is greater than positive infinity. /// <para/> /// NOTE: This was doubleToSortableLong() in Lucene /// </summary> - /// <seealso cref= #sortableLongToDouble </seealso> + /// <seealso cref="SortableInt64ToDouble(long)"/> public static long DoubleToSortableInt64(double val) { long f = Number.DoubleToInt64Bits(val); @@ -315,11 +316,11 @@ namespace Lucene.Net.Util } /// <summary> - /// Converts a sortable <code>long</code> back to a <code>double</code>. + /// Converts a sortable <see cref="long"/> back to a <see cref="double"/>. /// <para/> /// NOTE: This was sortableLongToDouble() in Lucene /// </summary> - /// <seealso cref= #doubleToSortableLong </seealso> + /// <seealso cref="DoubleToSortableInt64(double)"/> public static double SortableInt64ToDouble(long val) { if (val < 0) @@ -330,16 +331,16 @@ namespace Lucene.Net.Util } /// <summary> - /// Converts a <code>float</code> value to a sortable signed <code>int</code>. + /// Converts a <see cref="float"/> value to a sortable signed <see cref="int"/>. /// The value is converted by getting their IEEE 754 floating-point "float format" - /// bit layout and then some bits are swapped, to be able to compare the result as int. - /// By this the precision is not reduced, but the value can easily used as an int. - /// The sort order (including <seealso cref="Float#NaN"/>) is defined by - /// <seealso cref="Float#compareTo"/>; {@code NaN} is greater than positive infinity. + /// bit layout and then some bits are swapped, to be able to compare the result as <see cref="int"/>. + /// By this the precision is not reduced, but the value can easily used as an <see cref="int"/>. + /// The sort order (including <see cref="float.NaN"/>) is defined by + /// <seealso cref="float.CompareTo(float)"/>; <c>NaN</c> is greater than positive infinity. /// <para/> /// NOTE: This was floatToSortableInt() in Lucene /// </summary> - /// <seealso cref= #sortableIntToFloat </seealso> + /// <seealso cref="SortableInt32ToSingle(int)"/> public static int SingleToSortableInt32(float val) { int f = Number.SingleToInt32Bits(val); @@ -368,11 +369,11 @@ namespace Lucene.Net.Util /// <summary> /// Splits a long range recursively. /// You may implement a builder that adds clauses to a - /// <seealso cref="Lucene.Net.Search.BooleanQuery"/> for each call to its - /// <seealso cref="Int64RangeBuilder#addRange(BytesRef,BytesRef)"/> + /// <see cref="Lucene.Net.Search.BooleanQuery"/> for each call to its + /// <see cref="Int64RangeBuilder.AddRange(BytesRef, BytesRef)"/> /// method. /// <para/> - /// this method is used by <seealso cref="NumericRangeQuery"/>. + /// This method is used by <see cref="Search.NumericRangeQuery"/>. /// <para/> /// NOTE: This was splitLongRange() in Lucene /// </summary> @@ -382,13 +383,13 @@ namespace Lucene.Net.Util } /// <summary> - /// Splits an int range recursively. + /// Splits an <see cref="int"/> range recursively. /// You may implement a builder that adds clauses to a - /// <seealso cref="Lucene.Net.Search.BooleanQuery"/> for each call to its - /// <seealso cref="Int32RangeBuilder#addRange(BytesRef,BytesRef)"/> + /// <see cref="Lucene.Net.Search.BooleanQuery"/> for each call to its + /// <see cref="Int32RangeBuilder.AddRange(BytesRef, BytesRef)"/> /// method. /// <para/> - /// this method is used by <seealso cref="NumericRangeQuery"/>. + /// This method is used by <see cref="Search.NumericRangeQuery"/>. /// <para/> /// NOTE: This was splitIntRange() in Lucene /// </summary> @@ -398,7 +399,7 @@ namespace Lucene.Net.Util } /// <summary> - /// this helper does the splitting for both 32 and 64 bit. </summary> + /// This helper does the splitting for both 32 and 64 bit. </summary> private static void SplitRange(object builder, int valSize, int precisionStep, long minBound, long maxBound) { if (precisionStep < 1) @@ -441,7 +442,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Helper that delegates to correct range builder </summary> + /// Helper that delegates to correct range builder. </summary> private static void AddRange(object builder, int valSize, long minBound, long maxBound, int shift) { // for the max bound set all lower bits (that were shifted away): @@ -467,18 +468,18 @@ namespace Lucene.Net.Util } /// <summary> - /// Callback for <seealso cref="#splitLongRange"/>. - /// You need to overwrite only one of the methods. + /// Callback for <see cref="SplitInt64Range(Int64RangeBuilder, int, long, long)"/>. + /// You need to override only one of the methods. /// <para/> /// NOTE: This was LongRangeBuilder in Lucene - /// + /// <para/> /// @lucene.internal /// @since 2.9, API changed non backwards-compliant in 4.0 /// </summary> public abstract class Int64RangeBuilder { /// <summary> - /// Overwrite this method, if you like to receive the already prefix encoded range bounds. + /// Override this method, if you like to receive the already prefix encoded range bounds. /// You can directly build classical (inclusive) range queries from them. /// </summary> public virtual void AddRange(BytesRef minPrefixCoded, BytesRef maxPrefixCoded) @@ -487,7 +488,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Overwrite this method, if you like to receive the raw long range bounds. + /// Override this method, if you like to receive the raw long range bounds. /// You can use this for e.g. debugging purposes (print out range bounds). /// </summary> public virtual void AddRange(long min, long max, int shift) @@ -500,8 +501,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Callback for <seealso cref="#splitIntRange"/>. - /// You need to overwrite only one of the methods. + /// Callback for <see cref="SplitInt32Range(Int32RangeBuilder, int, int, int)"/>. + /// You need to override only one of the methods. /// <para/> /// NOTE: This was IntRangeBuilder in Lucene /// @@ -511,7 +512,7 @@ namespace Lucene.Net.Util public abstract class Int32RangeBuilder { /// <summary> - /// Overwrite this method, if you like to receive the already prefix encoded range bounds. + /// Override this method, if you like to receive the already prefix encoded range bounds. /// You can directly build classical range (inclusive) queries from them. /// </summary> public virtual void AddRange(BytesRef minPrefixCoded, BytesRef maxPrefixCoded) @@ -520,7 +521,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Overwrite this method, if you like to receive the raw int range bounds. + /// Override this method, if you like to receive the raw int range bounds. /// You can use this for e.g. debugging purposes (print out range bounds). /// </summary> public virtual void AddRange(int min, int max, int shift) @@ -533,15 +534,15 @@ namespace Lucene.Net.Util } /// <summary> - /// Filters the given <seealso cref="TermsEnum"/> by accepting only prefix coded 64 bit - /// terms with a shift value of <tt>0</tt>. + /// Filters the given <see cref="TermsEnum"/> by accepting only prefix coded 64 bit + /// terms with a shift value of <c>0</c>. /// <para/> /// NOTE: This was filterPrefixCodedLongs() in Lucene /// </summary> /// <param name="termsEnum"> - /// the terms enum to filter </param> - /// <returns> a filtered <seealso cref="TermsEnum"/> that only returns prefix coded 64 bit - /// terms with a shift value of <tt>0</tt>. </returns> + /// The terms enum to filter </param> + /// <returns> A filtered <see cref="TermsEnum"/> that only returns prefix coded 64 bit + /// terms with a shift value of <c>0</c>. </returns> public static TermsEnum FilterPrefixCodedInt64s(TermsEnum termsEnum) { return new FilteredTermsEnumAnonymousInnerClassHelper(termsEnum); @@ -561,15 +562,15 @@ namespace Lucene.Net.Util } /// <summary> - /// Filters the given <seealso cref="TermsEnum"/> by accepting only prefix coded 32 bit - /// terms with a shift value of <tt>0</tt>. + /// Filters the given <see cref="TermsEnum"/> by accepting only prefix coded 32 bit + /// terms with a shift value of <c>0</c>. /// <para/> /// NOTE: This was filterPrefixCodedInts() in Lucene /// </summary> /// <param name="termsEnum"> - /// the terms enum to filter </param> - /// <returns> a filtered <seealso cref="TermsEnum"/> that only returns prefix coded 32 bit - /// terms with a shift value of <tt>0</tt>. </returns> + /// The terms enum to filter </param> + /// <returns> A filtered <see cref="TermsEnum"/> that only returns prefix coded 32 bit + /// terms with a shift value of <c>0</c>. </returns> public static TermsEnum FilterPrefixCodedInt32s(TermsEnum termsEnum) { return new FilteredTermsEnumAnonymousInnerClassHelper2(termsEnum);
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/OfflineSorter.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/OfflineSorter.cs b/src/Lucene.Net/Util/OfflineSorter.cs index 9eca503..db34023 100644 --- a/src/Lucene.Net/Util/OfflineSorter.cs +++ b/src/Lucene.Net/Util/OfflineSorter.cs @@ -31,10 +31,10 @@ namespace Lucene.Net.Util /// <summary> /// On-disk sorting of byte arrays. Each byte array (entry) is a composed of the following /// fields: - /// <ul> - /// <li>(two bytes) length of the following byte array, - /// <li>exactly the above count of bytes for the sequence to be sorted. - /// </ul> + /// <list type="bullet"> + /// <item><description>(two bytes) length of the following byte array,</description></item> + /// <item><description>exactly the above count of bytes for the sequence to be sorted.</description></item> + /// </list> /// </summary> public sealed class OfflineSorter { @@ -69,8 +69,8 @@ namespace Lucene.Net.Util /// <summary> /// A bit more descriptive unit for constructors. /// </summary> - /// <seealso cref= #automatic() </seealso> - /// <seealso cref= #megabytes(long) </seealso> + /// <seealso cref="Automatic()"/> + /// <seealso cref="Megabytes(long)"/> public sealed class BufferSize { internal readonly int bytes; @@ -91,7 +91,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Creates a <seealso cref="BufferSize"/> in MB. The given + /// Creates a <see cref="BufferSize"/> in MB. The given /// values must be > 0 and < 2048. /// </summary> public static BufferSize Megabytes(long mb) @@ -101,7 +101,7 @@ namespace Lucene.Net.Util /// <summary> /// Approximately half of the currently available free heap, but no less - /// than <seealso cref="#ABSOLUTE_MIN_SORT_BUFFER_SIZE"/>. However if current heap allocation + /// than <see cref="ABSOLUTE_MIN_SORT_BUFFER_SIZE"/>. However if current heap allocation /// is insufficient or if there is a large portion of unallocated heap-space available /// for sorting consult with max allowed heap size. /// </summary> @@ -149,32 +149,32 @@ namespace Lucene.Net.Util private readonly OfflineSorter outerInstance; /// <summary> - /// number of temporary files created when merging partitions </summary> + /// Number of temporary files created when merging partitions </summary> public int TempMergeFiles { get; set; } /// <summary> - /// number of partition merges </summary> + /// Number of partition merges </summary> public int MergeRounds { get; set; } /// <summary> - /// number of lines of data read </summary> + /// Number of lines of data read </summary> public int Lines { get; set; } /// <summary> - /// time spent merging sorted partitions (in milliseconds) </summary> + /// Time spent merging sorted partitions (in milliseconds) </summary> public long MergeTime { get; set; } /// <summary> - /// time spent sorting data (in milliseconds) </summary> + /// Time spent sorting data (in milliseconds) </summary> public long SortTime { get; set; } /// <summary> - /// total time spent (in milliseconds) </summary> + /// Total time spent (in milliseconds) </summary> public long TotalTime { get; set; } /// <summary> - /// time spent in i/o read (in milliseconds) </summary> + /// Time spent in i/o read (in milliseconds) </summary> public long ReadTime { get; set; } /// <summary> - /// read buffer size (in bytes) </summary> - public long BufferSize { get; set; } + /// Read buffer size (in bytes) </summary> + public long BufferSize { get; set; } // LUCENENET TODO: API - make setter private /// <summary> - /// create a new SortInfo (with empty statistics) for debugging </summary> + /// Create a new <see cref="SortInfo"/> (with empty statistics) for debugging. </summary> public SortInfo(OfflineSorter outerInstance) { this.outerInstance = outerInstance; @@ -182,6 +182,9 @@ namespace Lucene.Net.Util InitializeInstanceFields(); } + /// <summary> + /// Returns a string representation of this object. + /// </summary> public override string ToString() { return string.Format(CultureInfo.InvariantCulture, @@ -207,8 +210,8 @@ namespace Lucene.Net.Util /// <summary> /// Defaults constructor. /// </summary> - /// <seealso cref= #defaultTempDir() </seealso> - /// <seealso cref= BufferSize#automatic() </seealso> + /// <seealso cref="DefaultTempDir()"/> + /// <seealso cref="BufferSize.Automatic()"/> public OfflineSorter() : this(DEFAULT_COMPARER, BufferSize.Automatic(), DefaultTempDir(), MAX_TEMPFILES) { @@ -217,8 +220,8 @@ namespace Lucene.Net.Util /// <summary> /// Defaults constructor with a custom comparer. /// </summary> - /// <seealso cref= #defaultTempDir() </seealso> - /// <seealso cref= BufferSize#automatic() </seealso> + /// <seealso cref="DefaultTempDir()"/> + /// <seealso cref="BufferSize.Automatic()"/> public OfflineSorter(IComparer<BytesRef> comparer) : this(comparer, BufferSize.Automatic(), DefaultTempDir(), MAX_TEMPFILES) { @@ -255,7 +258,7 @@ namespace Lucene.Net.Util // LUCENENET NOTE: Can't do this because another thread could recreate the file before we are done here. // and cause this to bomb. We use the existence of the file as an indicator that we are done using it. - //output.Delete(); + //output.Delete(); // LUCENENET TODO: BUG: Put this back in (we now have thread-safe file creation, so this should be like the original). var merges = new List<FileInfo>(); bool success2 = false; @@ -345,7 +348,7 @@ namespace Lucene.Net.Util /// <summary> /// Returns the default temporary directory. By default, the System's temp folder. If not accessible - /// or not available, an IOException is thrown + /// or not available, an <see cref="IOException"/> is thrown. /// </summary> public static DirectoryInfo DefaultTempDir() { @@ -394,7 +397,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Merge a list of sorted temporary files (partitions) into an output file </summary> + /// Merge a list of sorted temporary files (partitions) into an output file. </summary> internal void MergePartitions(IEnumerable<FileInfo> merges, FileInfo outputFile) { long start = Environment.TickCount; @@ -470,7 +473,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Read in a single partition of data </summary> + /// Read in a single partition of data. </summary> internal int ReadPartition(ByteSequencesReader reader) { long start = Environment.TickCount; @@ -504,22 +507,22 @@ namespace Lucene.Net.Util /// <summary> - /// Utility class to emit length-prefixed byte[] entries to an output stream for sorting. - /// Complementary to <seealso cref="ByteSequencesReader"/>. + /// Utility class to emit length-prefixed <see cref="T:byte[]"/> entries to an output stream for sorting. + /// Complementary to <see cref="ByteSequencesReader"/>. /// </summary> public class ByteSequencesWriter : IDisposable { private readonly DataOutput os; /// <summary> - /// Constructs a ByteSequencesWriter to the provided File </summary> + /// Constructs a <see cref="ByteSequencesWriter"/> to the provided <see cref="FileInfo"/>. </summary> public ByteSequencesWriter(FileInfo file) : this(NewBinaryWriterDataOutput(file)) { } /// <summary> - /// Constructs a ByteSequencesWriter to the provided DataOutput </summary> + /// Constructs a <see cref="ByteSequencesWriter"/> to the provided <see cref="DataOutput"/>. </summary> public ByteSequencesWriter(DataOutput os) { this.os = os; @@ -544,8 +547,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Writes a BytesRef. </summary> - /// <seealso cref= #write(byte[], int, int) </seealso> + /// Writes a <see cref="BytesRef"/>. </summary> + /// <seealso cref="Write(byte[], int, int)"/> public virtual void Write(BytesRef @ref) { Debug.Assert(@ref != null); @@ -554,7 +557,7 @@ namespace Lucene.Net.Util /// <summary> /// Writes a byte array. </summary> - /// <seealso cref= #write(byte[], int, int) </seealso> + /// <seealso cref="Write(byte[], int, int)"/> public virtual void Write(byte[] bytes) { Write(bytes, 0, bytes.Length); @@ -562,8 +565,8 @@ namespace Lucene.Net.Util /// <summary> /// Writes a byte array. - /// <p> - /// The length is written as a <code>short</code>, followed + /// <para/> + /// The length is written as a <see cref="short"/>, followed /// by the bytes. /// </summary> public virtual void Write(byte[] bytes, int off, int len) @@ -576,7 +579,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Closes the provided <seealso cref="DataOutput"/> if it is <seealso cref="IDisposable"/>. + /// Disposes the provided <see cref="DataOutput"/> if it is <see cref="IDisposable"/>. /// </summary> public void Dispose() { @@ -589,34 +592,34 @@ namespace Lucene.Net.Util } /// <summary> - /// Utility class to read length-prefixed byte[] entries from an input. - /// Complementary to <seealso cref="ByteSequencesWriter"/>. + /// Utility class to read length-prefixed <see cref="T:byte[]"/> entries from an input. + /// Complementary to <see cref="ByteSequencesWriter"/>. /// </summary> public class ByteSequencesReader : IDisposable { private readonly DataInput inputStream; /// <summary> - /// Constructs a ByteSequencesReader from the provided File </summary> + /// Constructs a <see cref="ByteSequencesReader"/> from the provided <see cref="FileInfo"/>. </summary> public ByteSequencesReader(FileInfo file) : this(new BinaryReaderDataInput(new BinaryReader(new FileStream(file.FullName, FileMode.Open, FileAccess.Read, FileShare.Read)))) { } /// <summary> - /// Constructs a ByteSequencesReader from the provided DataInput </summary> + /// Constructs a <see cref="ByteSequencesReader"/> from the provided <see cref="DataInput"/>. </summary> public ByteSequencesReader(DataInput inputStream) { this.inputStream = inputStream; } /// <summary> - /// Reads the next entry into the provided <seealso cref="BytesRef"/>. The internal + /// Reads the next entry into the provided <see cref="BytesRef"/>. The internal /// storage is resized if needed. /// </summary> - /// <returns> Returns <code>false</code> if EOF occurred when trying to read - /// the header of the next sequence. Returns <code>true</code> otherwise. </returns> - /// <exception cref="EOFException"> if the file ends before the full sequence is read. </exception> + /// <returns> Returns <c>false</c> if EOF occurred when trying to read + /// the header of the next sequence. Returns <c>true</c> otherwise. </returns> + /// <exception cref="EndOfStreamException"> If the file ends before the full sequence is read. </exception> public virtual bool Read(BytesRef @ref) { ushort length; @@ -639,11 +642,10 @@ namespace Lucene.Net.Util /// <summary> /// Reads the next entry and returns it if successful. /// </summary> - /// <seealso cref= #read(BytesRef) - /// </seealso> - /// <returns> Returns <code>null</code> if EOF occurred before the next entry + /// <seealso cref="Read(BytesRef)"/> + /// <returns> Returns <c>null</c> if EOF occurred before the next entry /// could be read. </returns> - /// <exception cref="EOFException"> if the file ends before the full sequence is read. </exception> + /// <exception cref="EndOfStreamException"> If the file ends before the full sequence is read. </exception> public virtual byte[] Read() { ushort length; @@ -663,7 +665,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Closes the provided <seealso cref="DataInput"/> if it is <seealso cref="IDisposable"/>. + /// Disposes the provided <see cref="DataInput"/> if it is <see cref="IDisposable"/>. /// </summary> public void Dispose() { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/OpenBitSet.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/OpenBitSet.cs b/src/Lucene.Net/Util/OpenBitSet.cs index c15adbe..5d7704f 100644 --- a/src/Lucene.Net/Util/OpenBitSet.cs +++ b/src/Lucene.Net/Util/OpenBitSet.cs @@ -27,54 +27,55 @@ namespace Lucene.Net.Util /// <summary> /// An "open" BitSet implementation that allows direct access to the array of words /// storing the bits. - /// <p/> - /// Unlike java.util.bitset, the fact that bits are packed into an array of longs - /// is part of the interface. this allows efficient implementation of other algorithms + /// <para/> + /// NOTE: This can be used in .NET any place where a <c>java.util.BitSet</c> is used in Java. + /// <para/> + /// Unlike <c>java.util.BitSet</c>, the fact that bits are packed into an array of longs + /// is part of the interface. This allows efficient implementation of other algorithms /// by someone other than the author. It also allows one to efficiently implement /// alternate serialization or interchange formats. - /// <p/> - /// <code>OpenBitSet</code> is faster than <code>java.util.BitSet</code> in most operations + /// <para/> + /// <see cref="OpenBitSet"/> is faster than <c>java.util.BitSet</c> in most operations /// and *much* faster at calculating cardinality of sets and results of set operations. /// It can also handle sets of larger cardinality (up to 64 * 2**32-1) - /// <p/> - /// The goals of <code>OpenBitSet</code> are the fastest implementation possible, and + /// <para/> + /// The goals of <see cref="OpenBitSet"/> are the fastest implementation possible, and /// maximum code reuse. Extra safety and encapsulation /// may always be built on top, but if that's built in, the cost can never be removed (and /// hence people re-implement their own version in order to get better performance). - /// If you want a "safe", totally encapsulated (and slower and limited) BitSet - /// class, use <code>java.util.BitSet</code>. - /// <p/> + /// <para/> /// <h3>Performance Results</h3> /// /// Test system: Pentium 4, Sun Java 1.5_06 -server -Xbatch -Xmx64M - /// <br/>BitSet size = 1,000,000 - /// <br/>Results are java.util.BitSet time divided by OpenBitSet time. - /// <table border="1"> - /// <tr> - /// <th></th> <th>cardinality</th> <th>intersect_count</th> <th>union</th> <th>nextSetBit</th> <th>get</th> <th>iterator</th> - /// </tr> - /// <tr> - /// <th>50% full</th> <td>3.36</td> <td>3.96</td> <td>1.44</td> <td>1.46</td> <td>1.99</td> <td>1.58</td> - /// </tr> - /// <tr> - /// <th>1% full</th> <td>3.31</td> <td>3.90</td> <td> </td> <td>1.04</td> <td> </td> <td>0.99</td> - /// </tr> - /// </table> - /// <br/> + /// <para/>BitSet size = 1,000,000 + /// <para/>Results are java.util.BitSet time divided by OpenBitSet time. + /// <list type="table"> + /// <listheader> + /// <term></term> <term>cardinality</term> <term>IntersectionCount</term> <term>Union</term> <term>NextSetBit</term> <term>Get</term> <term>GetIterator</term> + /// </listheader> + /// <item> + /// <term>50% full</term> <description>3.36</description> <description>3.96</description> <description>1.44</description> <description>1.46</description> <description>1.99</description> <description>1.58</description> + /// </item> + /// <item> + /// <term>1% full</term> <description>3.31</description> <description>3.90</description> <description> </description> <description>1.04</description> <description> </description> <description>0.99</description> + /// </item> + /// </list> + /// <para/> + /// <para/> /// Test system: AMD Opteron, 64 bit linux, Sun Java 1.5_06 -server -Xbatch -Xmx64M - /// <br/>BitSet size = 1,000,000 - /// <br/>Results are java.util.BitSet time divided by OpenBitSet time. - /// <table border="1"> - /// <tr> - /// <th></th> <th>cardinality</th> <th>intersect_count</th> <th>union</th> <th>nextSetBit</th> <th>get</th> <th>iterator</th> - /// </tr> - /// <tr> - /// <th>50% full</th> <td>2.50</td> <td>3.50</td> <td>1.00</td> <td>1.03</td> <td>1.12</td> <td>1.25</td> - /// </tr> - /// <tr> - /// <th>1% full</th> <td>2.51</td> <td>3.49</td> <td> </td> <td>1.00</td> <td> </td> <td>1.02</td> - /// </tr> - /// </table> + /// <para/>BitSet size = 1,000,000 + /// <para/>Results are java.util.BitSet time divided by OpenBitSet time. + /// <list type="table"> + /// <listheader> + /// <term></term> <term>cardinality</term> <term>IntersectionCount</term> <term>Union</term> <term>NextSetBit</term> <term>Get</term> <term>GetIterator</term> + /// </listheader> + /// <item> + /// <term>50% full</term> <description>2.50</description> <description>3.50</description> <description>1.00</description> <description>1.03</description> <description>1.12</description> <description>1.25</description> + /// </item> + /// <item> + /// <term>1% full</term> <description>2.51</description> <description>3.49</description> <description> </description> <description>1.00</description> <description> </description> <description>1.02</description> + /// </item> + /// </list> /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -88,7 +89,7 @@ namespace Lucene.Net.Util private long numBits; /// <summary> - /// Constructs an OpenBitSet large enough to hold {@code numBits}. </summary> + /// Constructs an <see cref="OpenBitSet"/> large enough to hold <paramref name="numBits"/>. </summary> public OpenBitSet(long numBits) { this.numBits = numBits; @@ -104,17 +105,16 @@ namespace Lucene.Net.Util } /// <summary> - /// Constructs an OpenBitSet from an existing long[]. - /// <p> + /// Constructs an <see cref="OpenBitSet"/> from an existing <see cref="T:long[]"/>. + /// <para/> /// The first 64 bits are in long[0], with bit index 0 at the least significant /// bit, and bit index 63 at the most significant. Given a bit index, the word /// containing it is long[index/64], and it is at bit number index%64 within /// that word. - /// <p> - /// numWords are the number of elements in the array that contain set bits - /// (non-zero longs). numWords should be <= bits.length, and any existing - /// words in the array at position >= numWords should be zero. - /// + /// <para/> + /// <paramref name="numWords"/> are the number of elements in the array that contain set bits + /// (non-zero longs). <paramref name="numWords"/> should be <= bits.Length, and any existing + /// words in the array at position >= numWords should be zero. /// </summary> public OpenBitSet(long[] bits, int numWords) { @@ -138,7 +138,7 @@ namespace Lucene.Net.Util } /// <summary> - /// this DocIdSet implementation is cacheable. </summary> + /// This DocIdSet implementation is cacheable. </summary> public override bool IsCacheable { get @@ -148,7 +148,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns the current capacity in bits (1 greater than the index of the last bit) </summary> + /// Returns the current capacity in bits (1 greater than the index of the last bit). </summary> public virtual long Capacity { get { return m_bits.Length << 6; } @@ -166,7 +166,8 @@ namespace Lucene.Net.Util //} /// <summary> - /// Returns the current capacity of this set. This is *not* equal to <seealso cref="#cardinality"/>. + /// Returns the current capacity of this set. This is *not* equal to <see cref="Cardinality()"/>. + /// <para/> /// NOTE: This is equivalent to size() or length() in Lucene. /// </summary> public virtual int Length @@ -175,7 +176,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns true if there are no set bits </summary> + /// Returns <c>true</c> if there are no set bits </summary> public virtual bool IsEmpty { get @@ -185,7 +186,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Expert: returns the long[] storing the bits </summary> + /// Expert: returns the <see cref="T:long[]"/> storing the bits. </summary> [WritableArray] public virtual long[] GetBits() { @@ -193,7 +194,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Expert: gets the number of longs in the array that are in use </summary> + /// Expert: gets the number of <see cref="long"/>s in the array that are in use. </summary> public virtual int NumWords { get @@ -203,7 +204,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns true or false for the specified bit index. </summary> + /// Returns <c>true</c> or <c>false</c> for the specified bit <paramref name="index"/>. </summary> public virtual bool Get(int index) { int i = index >> 6; // div 64 @@ -220,8 +221,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns true or false for the specified bit index. - /// The index should be less than the OpenBitSet size + /// Returns <c>true</c> or <c>false</c> for the specified bit <paramref name="index"/>. + /// The index should be less than the <see cref="Length"/>. /// </summary> public virtual bool FastGet(int index) { @@ -235,7 +236,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns true or false for the specified bit index + /// Returns <c>true</c> or <c>false</c> for the specified bit <paramref name="index"/>. /// </summary> public virtual bool Get(long index) { @@ -250,8 +251,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns true or false for the specified bit index. - /// The index should be less than the OpenBitSet size. + /// Returns <c>true</c> or <c>false</c> for the specified bit <paramref name="index"/>. + /// The index should be less than the <see cref="Length"/>. /// </summary> public virtual bool FastGet(long index) { @@ -275,8 +276,8 @@ namespace Lucene.Net.Util */ /// <summary> - /// returns 1 if the bit is set, 0 if not. - /// The index should be less than the OpenBitSet size + /// Returns 1 if the bit is set, 0 if not. + /// The <paramref name="index"/> should be less than the <see cref="Length"/>. /// </summary> public virtual int GetBit(int index) { @@ -296,7 +297,7 @@ namespace Lucene.Net.Util */ /// <summary> - /// sets a bit, expanding the set size if necessary </summary> + /// Sets a bit, expanding the set size if necessary. </summary> public virtual void Set(long index) { int wordNum = ExpandingWordNum(index); @@ -306,8 +307,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Sets the bit at the specified index. - /// The index should be less than the OpenBitSet size. + /// Sets the bit at the specified <paramref name="index"/>. + /// The <paramref name="index"/> should be less than the <see cref="Length"/>. /// </summary> public virtual void FastSet(int index) { @@ -319,8 +320,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Sets the bit at the specified index. - /// The index should be less than the OpenBitSet size. + /// Sets the bit at the specified <paramref name="index"/>. + /// The <paramref name="index"/> should be less than the <see cref="Length"/>. /// </summary> public virtual void FastSet(long index) { @@ -332,10 +333,10 @@ namespace Lucene.Net.Util } /// <summary> - /// Sets a range of bits, expanding the set size if necessary + /// Sets a range of bits, expanding the set size if necessary. /// </summary> - /// <param name="startIndex"> lower index </param> - /// <param name="endIndex"> one-past the last bit to set </param> + /// <param name="startIndex"> Lower index </param> + /// <param name="endIndex"> One-past the last bit to set </param> public virtual void Set(long startIndex, long endIndex) { if (endIndex <= startIndex) @@ -374,8 +375,8 @@ namespace Lucene.Net.Util } /// <summary> - /// clears a bit. - /// The index should be less than the OpenBitSet size. + /// Clears a bit. + /// The <paramref name="index"/> should be less than the <see cref="Length"/>. /// </summary> public virtual void FastClear(int index) { @@ -394,8 +395,8 @@ namespace Lucene.Net.Util } /// <summary> - /// clears a bit. - /// The index should be less than the OpenBitSet size. + /// Clears a bit. + /// The <paramref name="index"/> should be less than the <see cref="Length"/>. /// </summary> public virtual void FastClear(long index) { @@ -407,7 +408,7 @@ namespace Lucene.Net.Util } /// <summary> - /// clears a bit, allowing access beyond the current set size without changing the size. </summary> + /// Clears a bit, allowing access beyond the current set size without changing the size. </summary> public virtual void Clear(long index) { int wordNum = (int)(index >> 6); // div 64 @@ -423,8 +424,8 @@ namespace Lucene.Net.Util /// <summary> /// Clears a range of bits. Clearing past the end does not change the size of the set. /// </summary> - /// <param name="startIndex"> lower index </param> - /// <param name="endIndex"> one-past the last bit to clear </param> + /// <param name="startIndex"> Lower index </param> + /// <param name="endIndex"> One-past the last bit to clear </param> public virtual void Clear(int startIndex, int endIndex) { if (endIndex <= startIndex) @@ -470,8 +471,8 @@ namespace Lucene.Net.Util /// <summary> /// Clears a range of bits. Clearing past the end does not change the size of the set. /// </summary> - /// <param name="startIndex"> lower index </param> - /// <param name="endIndex"> one-past the last bit to clear </param> + /// <param name="startIndex"> Lower index </param> + /// <param name="endIndex"> One-past the last bit to clear </param> public virtual void Clear(long startIndex, long endIndex) { if (endIndex <= startIndex) @@ -514,7 +515,7 @@ namespace Lucene.Net.Util /// <summary> /// Sets a bit and returns the previous value. - /// The index should be less than the OpenBitSet size. + /// The <paramref name="index"/> should be less than the <see cref="Length"/>. /// </summary> public virtual bool GetAndSet(int index) { @@ -529,7 +530,7 @@ namespace Lucene.Net.Util /// <summary> /// Sets a bit and returns the previous value. - /// The index should be less than the OpenBitSet size. + /// The <paramref name="index"/> should be less than the <see cref="Length"/>. /// </summary> public virtual bool GetAndSet(long index) { @@ -543,8 +544,8 @@ namespace Lucene.Net.Util } /// <summary> - /// flips a bit. - /// The index should be less than the OpenBitSet size. + /// Flips a bit. + /// The <paramref name="index"/> should be less than the <see cref="Length"/>. /// </summary> public virtual void FastFlip(int index) { @@ -556,8 +557,8 @@ namespace Lucene.Net.Util } /// <summary> - /// flips a bit. - /// The index should be less than the OpenBitSet size. + /// Flips a bit. + /// The <paramref name="index"/> should be less than the <see cref="Length"/>. /// </summary> public virtual void FastFlip(long index) { @@ -569,7 +570,7 @@ namespace Lucene.Net.Util } /// <summary> - /// flips a bit, expanding the set size if necessary </summary> + /// Flips a bit, expanding the set size if necessary. </summary> public virtual void Flip(long index) { int wordNum = ExpandingWordNum(index); @@ -579,8 +580,8 @@ namespace Lucene.Net.Util } /// <summary> - /// flips a bit and returns the resulting bit value. - /// The index should be less than the OpenBitSet size. + /// Flips a bit and returns the resulting bit value. + /// The <paramref name="index"/> should be less than the <see cref="Length"/>. /// </summary> public virtual bool FlipAndGet(int index) { @@ -593,8 +594,8 @@ namespace Lucene.Net.Util } /// <summary> - /// flips a bit and returns the resulting bit value. - /// The index should be less than the OpenBitSet size. + /// Flips a bit and returns the resulting bit value. + /// The <paramref name="index"/> should be less than the <see cref="Length"/>. /// </summary> public virtual bool FlipAndGet(long index) { @@ -607,10 +608,10 @@ namespace Lucene.Net.Util } /// <summary> - /// Flips a range of bits, expanding the set size if necessary + /// Flips a range of bits, expanding the set size if necessary. /// </summary> - /// <param name="startIndex"> lower index </param> - /// <param name="endIndex"> one-past the last bit to flip </param> + /// <param name="startIndex"> Lower index </param> + /// <param name="endIndex"> One-past the last bit to flip </param> public virtual void Flip(long startIndex, long endIndex) { if (endIndex <= startIndex) @@ -624,14 +625,13 @@ namespace Lucene.Net.Util // word to be changed. int endWord = ExpandingWordNum(endIndex - 1); - /// <summary> - ///* Grrr, java shifting wraps around so -1L>>>64 == -1 - /// for that reason, make sure not to use endmask if the bits to flip will - /// be zero in the last word (redefine endWord to be the last changed...) - /// long startmask = -1L << (startIndex & 0x3f); // example: 11111...111000 - /// long endmask = -1L >>> (64-(endIndex & 0x3f)); // example: 00111...111111 - /// ** - /// </summary> + + //* Grrr, java shifting wraps around so -1L>>>64 == -1 + // for that reason, make sure not to use endmask if the bits to flip will + // be zero in the last word (redefine endWord to be the last changed...) + // long startmask = -1L << (startIndex & 0x3f); // example: 11111...111000 + // long endmask = -1L >>> (64-(endIndex & 0x3f)); // example: 00111...111111 + // ** long startmask = -1L << (int)startIndex; long endmask = (long)(0xffffffffffffffffUL >> (int)-endIndex); // 64-(endIndex&0x3f) is the same as -endIndex due to wrap @@ -673,7 +673,10 @@ namespace Lucene.Net.Util } */ - /// <returns> the number of set bits </returns> + /// <summary> + /// Get the number of set bits. + /// </summary> + /// <returns> The number of set bits. </returns> public virtual long Cardinality() { return BitUtil.Pop_Array(m_bits, 0, m_wlen); @@ -740,8 +743,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns the index of the first set bit starting at the index specified. - /// -1 is returned if there are no more set bits. + /// Returns the index of the first set bit starting at the <paramref name="index"/> specified. + /// -1 is returned if there are no more set bits. /// </summary> public virtual int NextSetBit(int index) { @@ -771,8 +774,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns the index of the first set bit starting at the index specified. - /// -1 is returned if there are no more set bits. + /// Returns the index of the first set bit starting at the <paramref name="index"/> specified. + /// -1 is returned if there are no more set bits. /// </summary> public virtual long NextSetBit(long index) { @@ -803,8 +806,8 @@ namespace Lucene.Net.Util /// <summary> /// Returns the index of the first set bit starting downwards at - /// the index specified. - /// -1 is returned if there are no more set bits. + /// the <paramref name="index"/> specified. + /// -1 is returned if there are no more set bits. /// </summary> public virtual int PrevSetBit(int index) { @@ -850,8 +853,8 @@ namespace Lucene.Net.Util /// <summary> /// Returns the index of the first set bit starting downwards at - /// the index specified. - /// -1 is returned if there are no more set bits. + /// the <paramref name="index"/> specified. + /// -1 is returned if there are no more set bits. /// </summary> public virtual long PrevSetBit(long index) { @@ -947,7 +950,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Remove all elements set in other. this = this AND_NOT other </summary> + /// Remove all elements set in other. this = this AND_NOT other. </summary> public virtual void Remove(OpenBitSet other) { int idx = Math.Min(m_wlen, other.m_wlen); @@ -1002,7 +1005,7 @@ namespace Lucene.Net.Util } /// <summary> - /// returns true if the sets have any elements in common </summary> + /// returns <c>true</c> if the sets have any elements in common. </summary> public virtual bool Intersects(OpenBitSet other) { int pos = Math.Min(this.m_wlen, other.m_wlen); @@ -1019,7 +1022,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Expand the long[] with the size given as a number of words (64 bit longs). </summary> + /// Expand the <see cref="T:long[]"/> with the size given as a number of words (64 bit longs). </summary> public virtual void EnsureCapacityWords(int numWords) { m_bits = ArrayUtil.Grow(m_bits, numWords); @@ -1028,7 +1031,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Ensure that the long[] is big enough to hold numBits, expanding it if + /// Ensure that the <see cref="T:long[]"/> is big enough to hold numBits, expanding it if /// necessary. /// </summary> public virtual void EnsureCapacity(long numBits) @@ -1054,14 +1057,14 @@ namespace Lucene.Net.Util } /// <summary> - /// returns the number of 64 bit words it would take to hold numBits </summary> + /// Returns the number of 64 bit words it would take to hold <paramref name="numBits"/>. </summary> public static int Bits2words(long numBits) { return (int)(((numBits - 1) >> 6) + 1); } /// <summary> - /// returns true if both sets have the same bits set </summary> + /// Returns <c>true</c> if both sets have the same bits set. </summary> public override bool Equals(object o) { if (this == o) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/OpenBitSetDISI.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/OpenBitSetDISI.cs b/src/Lucene.Net/Util/OpenBitSetDISI.cs index 5749598..d7bb489 100644 --- a/src/Lucene.Net/Util/OpenBitSetDISI.cs +++ b/src/Lucene.Net/Util/OpenBitSetDISI.cs @@ -22,8 +22,8 @@ namespace Lucene.Net.Util using DocIdSetIterator = Lucene.Net.Search.DocIdSetIterator; /// <summary> - /// OpenBitSet with added methods to bulk-update the bits - /// from a <seealso cref="DocIdSetIterator"/>. + /// <see cref="OpenBitSet"/> with added methods to bulk-update the bits + /// from a <see cref="DocIdSetIterator"/>. (DISI stands for <see cref="DocIdSetIterator"/>). /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -31,10 +31,10 @@ namespace Lucene.Net.Util public class OpenBitSetDISI : OpenBitSet { /// <summary> - /// Construct an OpenBitSetDISI with its bits set - /// from the doc ids of the given DocIdSetIterator. + /// Construct an <see cref="OpenBitSetDISI"/> with its bits set + /// from the doc ids of the given <see cref="DocIdSetIterator"/>. /// Also give a maximum size one larger than the largest doc id for which a - /// bit may ever be set on this OpenBitSetDISI. + /// bit may ever be set on this <see cref="OpenBitSetDISI"/>. /// </summary> public OpenBitSetDISI(DocIdSetIterator disi, int maxSize) : base(maxSize) @@ -43,9 +43,9 @@ namespace Lucene.Net.Util } /// <summary> - /// Construct an OpenBitSetDISI with no bits set, and a given maximum size + /// Construct an <see cref="OpenBitSetDISI"/> with no bits set, and a given maximum size /// one larger than the largest doc id for which a bit may ever be set - /// on this OpenBitSetDISI. + /// on this <see cref="OpenBitSetDISI"/>. /// </summary> public OpenBitSetDISI(int maxSize) : base(maxSize) @@ -53,7 +53,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Perform an inplace OR with the doc ids from a given DocIdSetIterator, + /// Perform an inplace OR with the doc ids from a given <see cref="DocIdSetIterator"/>, /// setting the bit for each such doc id. /// These doc ids should be smaller than the maximum size passed to the /// constructor. @@ -69,7 +69,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Perform an inplace AND with the doc ids from a given DocIdSetIterator, + /// Perform an inplace AND with the doc ids from a given <see cref="DocIdSetIterator"/>, /// leaving only the bits set for which the doc ids are in common. /// These doc ids should be smaller than the maximum size passed to the /// constructor. @@ -90,7 +90,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Perform an inplace NOT with the doc ids from a given DocIdSetIterator, + /// Perform an inplace NOT with the doc ids from a given <see cref="DocIdSetIterator"/>, /// clearing all the bits for each such doc id. /// These doc ids should be smaller than the maximum size passed to the /// constructor. @@ -106,7 +106,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Perform an inplace XOR with the doc ids from a given DocIdSetIterator, + /// Perform an inplace XOR with the doc ids from a given <see cref="DocIdSetIterator"/>, /// flipping all the bits for each such doc id. /// These doc ids should be smaller than the maximum size passed to the /// constructor. http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/OpenBitSetIterator.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/OpenBitSetIterator.cs b/src/Lucene.Net/Util/OpenBitSetIterator.cs index e7dbd45..769aeba 100644 --- a/src/Lucene.Net/Util/OpenBitSetIterator.cs +++ b/src/Lucene.Net/Util/OpenBitSetIterator.cs @@ -20,8 +20,8 @@ namespace Lucene.Net.Util using DocIdSetIterator = Lucene.Net.Search.DocIdSetIterator; /// <summary> - /// An iterator to iterate over set bits in an OpenBitSet. - /// this is faster than nextSetBit() for iterating over the complete set of bits, + /// An iterator to iterate over set bits in an <see cref="OpenBitSet"/>. + /// this is faster than <see cref="OpenBitSet.NextSetBit(long)"/> for iterating over the complete set of bits, /// especially when the density of the bits set is high. /// </summary> public class OpenBitSetIterator : DocIdSetIterator @@ -71,29 +71,27 @@ namespace Lucene.Net.Util indexArray = BitUtil.BitList((byte)word); } - /// <summary> - ///*** alternate shift implementations - /// // 32 bit shifts, but a long shift needed at the end - /// private void shift2() { - /// int y = (int)word; - /// if (y==0) {wordShift +=32; y = (int)(word >>>32); } - /// if ((y & 0x0000FFFF) == 0) { wordShift +=16; y>>>=16; } - /// if ((y & 0x000000FF) == 0) { wordShift +=8; y>>>=8; } - /// indexArray = bitlist[y & 0xff]; - /// word >>>= (wordShift +1); - /// } - /// - /// private void shift3() { - /// int lower = (int)word; - /// int lowByte = lower & 0xff; - /// if (lowByte != 0) { - /// indexArray=bitlist[lowByte]; - /// return; - /// } - /// shift(); - /// } - /// ***** - /// </summary> + //*** alternate shift implementations + // // 32 bit shifts, but a long shift needed at the end + // private void shift2() { + // int y = (int)word; + // if (y==0) {wordShift +=32; y = (int)(word >>>32); } + // if ((y & 0x0000FFFF) == 0) { wordShift +=16; y>>>=16; } + // if ((y & 0x000000FF) == 0) { wordShift +=8; y>>>=8; } + // indexArray = bitlist[y & 0xff]; + // word >>>= (wordShift +1); + // } + // + // private void shift3() { + // int lower = (int)word; + // int lowByte = lower & 0xff; + // if (lowByte != 0) { + // indexArray=bitlist[lowByte]; + // return; + // } + // shift(); + // } + // ***** public override int NextDoc() { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/PForDeltaDocIdSet.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/PForDeltaDocIdSet.cs b/src/Lucene.Net/Util/PForDeltaDocIdSet.cs index 0920ca3..968502e 100644 --- a/src/Lucene.Net/Util/PForDeltaDocIdSet.cs +++ b/src/Lucene.Net/Util/PForDeltaDocIdSet.cs @@ -27,12 +27,12 @@ namespace Lucene.Net.Util using PackedInt32s = Lucene.Net.Util.Packed.PackedInt32s; /// <summary> - /// <seealso cref="DocIdSet"/> implementation based on pfor-delta encoding. - /// <p>this implementation is inspired from LinkedIn's Kamikaze + /// <see cref="DocIdSet"/> implementation based on pfor-delta encoding. + /// <para>This implementation is inspired from LinkedIn's Kamikaze /// (http://data.linkedin.com/opensource/kamikaze) and Daniel Lemire's JavaFastPFOR - /// (https://github.com/lemire/JavaFastPFOR).</p> - /// <p>On the contrary to the original PFOR paper, exceptions are encoded with - /// FOR instead of Simple16.</p> + /// (https://github.com/lemire/JavaFastPFOR).</para> + /// <para>On the contrary to the original PFOR paper, exceptions are encoded with + /// FOR instead of Simple16.</para> /// </summary> public sealed class PForDeltaDocIdSet : DocIdSet { @@ -65,7 +65,7 @@ namespace Lucene.Net.Util } /// <summary> - /// A builder for <seealso cref="PForDeltaDocIdSet"/>. </summary> + /// A builder for <see cref="PForDeltaDocIdSet"/>. </summary> public class Builder { internal readonly GrowableByteArrayDataOutput data; @@ -98,7 +98,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Set the index interval. Every <code>indexInterval</code>-th block will + /// Set the index interval. Every <paramref name="indexInterval"/>-th block will /// be stored in the index. Set to <see cref="int.MaxValue"/> to disable indexing. /// </summary> public virtual Builder SetIndexInterval(int indexInterval) @@ -131,7 +131,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Convenience method to add the content of a <seealso cref="DocIdSetIterator"/> to this builder. </summary> + /// Convenience method to add the content of a <see cref="DocIdSetIterator"/> to this builder. </summary> public virtual Builder Add(DocIdSetIterator it) { for (int doc = it.NextDoc(); doc != DocIdSetIterator.NO_MORE_DOCS; doc = it.NextDoc()) @@ -313,7 +313,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Build the <seealso cref="PForDeltaDocIdSet"/> instance. </summary> + /// Build the <see cref="PForDeltaDocIdSet"/> instance. </summary> public virtual PForDeltaDocIdSet Build() { Debug.Assert(bufferSize < BLOCK_SIZE); @@ -599,7 +599,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Return the number of documents in this <seealso cref="DocIdSet"/> in constant time. </summary> + /// Return the number of documents in this <see cref="DocIdSet"/> in constant time. </summary> public int Cardinality() { return cardinality; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/PagedBytes.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/PagedBytes.cs b/src/Lucene.Net/Util/PagedBytes.cs index a40c3b3..4a6e4bd 100644 --- a/src/Lucene.Net/Util/PagedBytes.cs +++ b/src/Lucene.Net/Util/PagedBytes.cs @@ -26,13 +26,12 @@ namespace Lucene.Net.Util using IndexInput = Lucene.Net.Store.IndexInput; /// <summary> - /// Represents a logical byte[] as a series of pages. You - /// can write-once into the logical byte[] (append only), - /// using copy, and then retrieve slices (BytesRef) into it - /// using fill. - /// + /// Represents a logical <see cref="T:byte[]"/> as a series of pages. You + /// can write-once into the logical <see cref="T:byte[]"/> (append only), + /// using copy, and then retrieve slices (<see cref="BytesRef"/>) into it + /// using fill. + /// <para/> /// @lucene.internal - /// /// </summary> // TODO: refactor this, byteblockpool, fst.bytestore, and any // other "shift/mask big arrays". there are too many of these classes! @@ -55,10 +54,10 @@ namespace Lucene.Net.Util private static readonly byte[] EMPTY_BYTES = new byte[0]; /// <summary> - /// Provides methods to read BytesRefs from a frozen - /// PagedBytes. + /// Provides methods to read <see cref="BytesRef"/>s from a frozen + /// <see cref="PagedBytes"/>. /// </summary> - /// <seealso cref= #freeze </seealso> + /// <seealso cref="Freeze(bool)"/> public sealed class Reader { private readonly byte[][] blocks; @@ -85,14 +84,13 @@ namespace Lucene.Net.Util } /// <summary> - /// Gets a slice out of <seealso cref="PagedBytes"/> starting at <i>start</i> with a - /// given length. Iff the slice spans across a block border this method will + /// Gets a slice out of <see cref="PagedBytes"/> starting at <paramref name="start"/> with a + /// given length. If the slice spans across a block border this method will /// allocate sufficient resources and copy the paged data. - /// <p> + /// <para> /// Slices spanning more than two blocks are not supported. - /// </p> + /// </para> /// @lucene.internal - /// /// </summary> public void FillSlice(BytesRef b, long start, int length) { @@ -122,14 +120,12 @@ namespace Lucene.Net.Util } /// <summary> - /// Reads length as 1 or 2 byte vInt prefix, starting at <i>start</i>. - /// <p> + /// Reads length as 1 or 2 byte vInt prefix, starting at <paramref name="start"/>. + /// <para> /// <b>Note:</b> this method does not support slices spanning across block /// borders. - /// </p> - /// + /// </para> /// @lucene.internal - /// /// </summary> // TODO: this really needs to be refactored into fieldcacheimpl public void Fill(BytesRef b, long start) @@ -152,7 +148,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns approximate RAM bytes used </summary> + /// Returns approximate RAM bytes used. </summary> public long RamBytesUsed() { return ((blocks != null) ? (blockSize * blocks.Length) : 0); @@ -161,7 +157,7 @@ namespace Lucene.Net.Util /// <summary> /// 1<<blockBits must be bigger than biggest single - /// BytesRef slice that will be pulled + /// <see cref="BytesRef"/> slice that will be pulled. /// </summary> public PagedBytes(int blockBits) { @@ -174,7 +170,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Read this many bytes from in </summary> + /// Read this many bytes from <paramref name="in"/>. </summary> public void Copy(IndexInput @in, long byteCount) { while (byteCount > 0) @@ -207,9 +203,9 @@ namespace Lucene.Net.Util } /// <summary> - /// Copy BytesRef in, setting BytesRef out to the result. - /// Do not use this if you will use freeze(true). - /// this only supports bytes.length <= blockSize + /// Copy <see cref="BytesRef"/> in, setting <see cref="BytesRef"/> out to the result. + /// Do not use this if you will use <c>Freeze(true)</c>. + /// This only supports <c>bytes.Length <= blockSize</c>/ /// </summary> public void Copy(BytesRef bytes, BytesRef @out) { @@ -238,7 +234,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Commits final byte[], trimming it if necessary and if trim=true </summary> + /// Commits final <see cref="T:byte[]"/>, trimming it if necessary and if <paramref name="trim"/>=true. </summary> public Reader Freeze(bool trim) { if (frozen) @@ -266,7 +262,7 @@ namespace Lucene.Net.Util return new PagedBytes.Reader(this); } - public long Pointer + public long Pointer // LUCENENET TODO: API - Change to GetPointer() (makes conversion) { get { @@ -290,7 +286,7 @@ namespace Lucene.Net.Util /// <summary> /// Copy bytes in, writing the length as a 1 or 2 byte - /// vInt prefix. + /// vInt prefix. /// </summary> // TODO: this really needs to be refactored into fieldcacheimpl public long CopyUsingLengthPrefix(BytesRef bytes) @@ -355,7 +351,7 @@ namespace Lucene.Net.Util /// <summary> /// Returns the current byte position. </summary> - public long Position + public long Position // LUCENENET TODO: API - Change to GetPosition() (makes conversion) { get { @@ -484,7 +480,7 @@ namespace Lucene.Net.Util /// <summary> /// Return the current byte position. </summary> - public long Position + public long Position // LUCENENET TODO: API - Change to GetPosition() (makes conversion) { get { @@ -494,8 +490,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns a DataInput to read values from this - /// PagedBytes instance. + /// Returns a <see cref="DataInput"/> to read values from this + /// <see cref="PagedBytes"/> instance. /// </summary> public PagedBytesDataInput GetDataInput() { @@ -507,10 +503,10 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns a DataOutput that you may use to write into - /// this PagedBytes instance. If you do this, you should - /// not call the other writing methods (eg, copy); - /// results are undefined. + /// Returns a <see cref="DataOutput"/> that you may use to write into + /// this <see cref="PagedBytes"/> instance. If you do this, you should + /// not call the other writing methods (eg, copy); + /// results are undefined. /// </summary> public PagedBytesDataOutput GetDataOutput() { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/PrintStreamInfoStream.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/PrintStreamInfoStream.cs b/src/Lucene.Net/Util/PrintStreamInfoStream.cs index 63d0f95..455e273 100644 --- a/src/Lucene.Net/Util/PrintStreamInfoStream.cs +++ b/src/Lucene.Net/Util/PrintStreamInfoStream.cs @@ -23,12 +23,12 @@ namespace Lucene.Net.Util */ /// <summary> - /// InfoStream implementation over a <seealso cref="PrintStream"/> - /// such as <code>System.out</code>. - /// + /// InfoStream implementation over a <see cref="TextWriter"/> + /// such as <see cref="Console.Out"/>. + /// <para/> /// @lucene.internal /// </summary> - public class PrintStreamInfoStream : InfoStream + public class PrintStreamInfoStream : InfoStream // LUCENENET TODO: API - Rename to TextWriterInfoStream { // Used for printing messages private static readonly AtomicInt32 MESSAGE_ID = new AtomicInt32();
