Lucene.Net.Util: Fixed up documentation comments, types beginning with A-G
Project: http://git-wip-us.apache.org/repos/asf/lucenenet/repo Commit: http://git-wip-us.apache.org/repos/asf/lucenenet/commit/d7cb70c4 Tree: http://git-wip-us.apache.org/repos/asf/lucenenet/tree/d7cb70c4 Diff: http://git-wip-us.apache.org/repos/asf/lucenenet/diff/d7cb70c4 Branch: refs/heads/master Commit: d7cb70c465b8320816f068b7f9604de21fffbac8 Parents: ef2d090 Author: Shad Storhaug <[email protected]> Authored: Sun Jun 4 03:08:38 2017 +0700 Committer: Shad Storhaug <[email protected]> Committed: Sun Jun 4 03:22:58 2017 +0700 ---------------------------------------------------------------------- CONTRIBUTING.md | 2 +- src/Lucene.Net/Lucene.Net.csproj | 2 +- src/Lucene.Net/Util/Accountable.cs | 2 +- src/Lucene.Net/Util/ArrayInPlaceMergeSorter.cs | 5 +- src/Lucene.Net/Util/ArrayIntroSorter.cs | 5 +- src/Lucene.Net/Util/ArrayTimSorter.cs | 5 +- src/Lucene.Net/Util/ArrayUtil.cs | 115 ++++++++------- src/Lucene.Net/Util/AttributeImpl.cs | 52 +++++-- src/Lucene.Net/Util/AttributeReflector.cs | 42 ++++++ src/Lucene.Net/Util/AttributeSource.cs | 144 ++++++++++--------- src/Lucene.Net/Util/BitUtil.cs | 45 +++--- src/Lucene.Net/Util/Bits.cs | 7 +- src/Lucene.Net/Util/BroadWord.cs | 54 +++---- src/Lucene.Net/Util/ByteBlockPool.cs | 58 ++++---- src/Lucene.Net/Util/BytesRef.cs | 88 ++++++------ src/Lucene.Net/Util/BytesRefArray.cs | 52 +++---- src/Lucene.Net/Util/BytesRefHash.cs | 139 +++++++++--------- src/Lucene.Net/Util/BytesRefIterator.cs | 23 +-- src/Lucene.Net/Util/CharsRef.cs | 48 ++++--- src/Lucene.Net/Util/CloseableThreadLocal.cs | 47 +++--- src/Lucene.Net/Util/CollectionUtil.cs | 8 +- src/Lucene.Net/Util/CommandLineUtil.cs | 39 +++-- src/Lucene.Net/Util/Constants.cs | 18 ++- src/Lucene.Net/Util/Counter.cs | 16 +-- src/Lucene.Net/Util/DocIdBitSet.cs | 6 +- src/Lucene.Net/Util/DoubleBarrelLRUCache.cs | 10 +- src/Lucene.Net/Util/FieldCacheSanityChecker.cs | 86 +++++------ src/Lucene.Net/Util/FilterIterator.cs | 6 +- src/Lucene.Net/Util/FixedBitSet.cs | 62 ++++---- .../Util/GrowableByteArrayDataOutput.cs | 5 +- src/Lucene.Net/Util/IAttributeReflector.cs | 29 ---- 31 files changed, 643 insertions(+), 577 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/CONTRIBUTING.md ---------------------------------------------------------------------- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ca36869..cec7578 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,7 +53,7 @@ helpers to help with that, see for examples see our [Java style methods to avoid 1. Lucene.Net.Core (project) 1. Codecs (namespace) 2. Support (namespace) - 3. Util (namespace) (Except for Util.Fst) + 3. Util (namespace) Types starting with I-Z, Util.Automaton, Util.Mutable, and Util.Packed. 2. Lucene.Net.Codecs (project) See [Documenting Lucene.Net](https://cwiki.apache.org/confluence/display/LUCENENET/Documenting+Lucene.Net) for instructions. http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Lucene.Net.csproj ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Lucene.Net.csproj b/src/Lucene.Net/Lucene.Net.csproj index 3352bf3..2a6b11d 100644 --- a/src/Lucene.Net/Lucene.Net.csproj +++ b/src/Lucene.Net/Lucene.Net.csproj @@ -733,6 +733,7 @@ <Compile Include="Util\ArrayUtil.cs" /> <Compile Include="Util\Attribute.cs" /> <Compile Include="Util\AttributeImpl.cs" /> + <Compile Include="Util\AttributeReflector.cs" /> <Compile Include="Util\AttributeSource.cs" /> <Compile Include="Util\Automaton\Automaton.cs" /> <Compile Include="Util\Automaton\AutomatonProvider.cs" /> @@ -793,7 +794,6 @@ <Compile Include="Util\Fst\ReverseBytesReader.cs" /> <Compile Include="Util\Fst\Util.cs" /> <Compile Include="Util\GrowableByteArrayDataOutput.cs" /> - <Compile Include="Util\IAttributeReflector.cs" /> <Compile Include="Util\IndexableBinaryStringTools.cs" /> <Compile Include="Util\InfoStream.cs" /> <Compile Include="Util\InPlaceMergeSorter.cs" /> http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/Accountable.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/Accountable.cs b/src/Lucene.Net/Util/Accountable.cs index 9dda797..561669b 100644 --- a/src/Lucene.Net/Util/Accountable.cs +++ b/src/Lucene.Net/Util/Accountable.cs @@ -19,7 +19,7 @@ /// <summary> /// An object whose RAM usage can be computed. - /// + /// <para/> /// @lucene.internal /// </summary> public interface IAccountable // LUCENENET NOTE: This interface wasn't added until Lucene 4.9 http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/ArrayInPlaceMergeSorter.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/ArrayInPlaceMergeSorter.cs b/src/Lucene.Net/Util/ArrayInPlaceMergeSorter.cs index 3ce6826..174099a 100644 --- a/src/Lucene.Net/Util/ArrayInPlaceMergeSorter.cs +++ b/src/Lucene.Net/Util/ArrayInPlaceMergeSorter.cs @@ -20,7 +20,8 @@ namespace Lucene.Net.Util */ /// <summary> - /// An <seealso cref="InPlaceMergeSorter"/> for object arrays. + /// An <see cref="InPlaceMergeSorter"/> for object arrays. + /// <para/> /// @lucene.internal /// </summary> internal sealed class ArrayInPlaceMergeSorter<T> : InPlaceMergeSorter @@ -29,7 +30,7 @@ namespace Lucene.Net.Util private readonly IComparer<T> comparer; /// <summary> - /// Create a new <seealso cref="ArrayInPlaceMergeSorter"/>. </summary> + /// Create a new <see cref="ArrayInPlaceMergeSorter{T}"/>. </summary> public ArrayInPlaceMergeSorter(T[] arr, IComparer<T> comparer) { this.arr = arr; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/ArrayIntroSorter.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/ArrayIntroSorter.cs b/src/Lucene.Net/Util/ArrayIntroSorter.cs index 7c7c1da..5f71168 100644 --- a/src/Lucene.Net/Util/ArrayIntroSorter.cs +++ b/src/Lucene.Net/Util/ArrayIntroSorter.cs @@ -20,7 +20,8 @@ namespace Lucene.Net.Util */ /// <summary> - /// An <seealso cref="IntroSorter"/> for object arrays. + /// An <see cref="IntroSorter"/> for object arrays. + /// <para/> /// @lucene.internal /// </summary> internal sealed class ArrayIntroSorter<T> : IntroSorter @@ -30,7 +31,7 @@ namespace Lucene.Net.Util private T pivot; /// <summary> - /// Create a new <seealso cref="ArrayInPlaceMergeSorter"/>. </summary> + /// Create a new <see cref="ArrayIntroSorter{T}"/>. </summary> public ArrayIntroSorter(T[] arr, IComparer<T> comparer) { this.arr = arr; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/ArrayTimSorter.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/ArrayTimSorter.cs b/src/Lucene.Net/Util/ArrayTimSorter.cs index 79b5cb2..79e1cd8 100644 --- a/src/Lucene.Net/Util/ArrayTimSorter.cs +++ b/src/Lucene.Net/Util/ArrayTimSorter.cs @@ -21,7 +21,8 @@ namespace Lucene.Net.Util */ /// <summary> - /// A <seealso cref="TimSorter"/> for object arrays. + /// A <see cref="TimSorter"/> for object arrays. + /// <para/> /// @lucene.internal /// </summary> internal sealed class ArrayTimSorter<T> : TimSorter @@ -31,7 +32,7 @@ namespace Lucene.Net.Util private readonly T[] tmp; /// <summary> - /// Create a new <seealso cref="ArrayTimSorter"/>. </summary> + /// Create a new <see cref="ArrayTimSorter{T}"/>. </summary> public ArrayTimSorter(T[] arr, IComparer<T> comparer, int maxTempSlots) : base(maxTempSlots) { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/ArrayUtil.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/ArrayUtil.cs b/src/Lucene.Net/Util/ArrayUtil.cs index 2e45dfc..de8b2d4 100644 --- a/src/Lucene.Net/Util/ArrayUtil.cs +++ b/src/Lucene.Net/Util/ArrayUtil.cs @@ -24,18 +24,18 @@ namespace Lucene.Net.Util /// <summary> /// Methods for manipulating arrays. - /// + /// <para/> /// @lucene.internal /// </summary> public sealed class ArrayUtil { /// <summary> /// Maximum length for an array; we set this to "a - /// bit" below <see cref="int.MaxValue"/> because the exact max - /// allowed byte[] is JVM dependent, so we want to avoid - /// a case where a large value worked during indexing on - /// one JVM but failed later at search time with a - /// different JVM. + /// bit" below <see cref="int.MaxValue"/> because the exact max + /// allowed byte[] is JVM dependent, so we want to avoid + /// a case where a large value worked during indexing on + /// one JVM but failed later at search time with a + /// different JVM. /// </summary> public static readonly int MAX_ARRAY_LENGTH = int.MaxValue - 256; @@ -51,47 +51,47 @@ namespace Lucene.Net.Util */ /// <summary> - /// Parses the string argument as if it was an int value and returns the - /// result. Throws NumberFormatException if the string does not represent an + /// Parses the string argument as if it was an <see cref="int"/> value and returns the + /// result. Throws <see cref="FormatException"/> if the string does not represent an /// int quantity. /// <para/> /// NOTE: This was parseInt() in Lucene /// </summary> - /// <param name="chars"> a string representation of an int quantity. </param> - /// <returns> int the value represented by the argument </returns> - /// <exception cref="NumberFormatException"> if the argument could not be parsed as an int quantity. </exception> + /// <param name="chars"> A string representation of an int quantity. </param> + /// <returns> The value represented by the argument </returns> + /// <exception cref="FormatException"> If the argument could not be parsed as an int quantity. </exception> public static int ParseInt32(char[] chars) { return ParseInt32(chars, 0, chars.Length, 10); } /// <summary> - /// Parses a char array into an int. + /// Parses a char array into an <see cref="int"/>. /// <para/> /// NOTE: This was parseInt() in Lucene /// </summary> - /// <param name="chars"> the character array </param> + /// <param name="chars"> The character array </param> /// <param name="offset"> The offset into the array </param> /// <param name="len"> The length </param> - /// <returns> the int </returns> - /// <exception cref="NumberFormatException"> if it can't parse </exception> + /// <returns> the <see cref="int"/> </returns> + /// <exception cref="FormatException"> If it can't parse </exception> public static int ParseInt32(char[] chars, int offset, int len) { return ParseInt32(chars, offset, len, 10); } /// <summary> - /// Parses the string argument as if it was an int value and returns the - /// result. Throws NumberFormatException if the string does not represent an - /// int quantity. The second argument specifies the radix to use when parsing + /// Parses the string argument as if it was an <see cref="int"/> value and returns the + /// result. Throws <see cref="FormatException"/> if the string does not represent an + /// <see cref="int"/> quantity. The second argument specifies the radix to use when parsing /// the value. /// <para/> /// NOTE: This was parseInt() in Lucene /// </summary> - /// <param name="chars"> a string representation of an int quantity. </param> - /// <param name="radix"> the base to use for conversion. </param> - /// <returns> int the value represented by the argument </returns> - /// <exception cref="NumberFormatException"> if the argument could not be parsed as an int quantity. </exception> + /// <param name="chars"> A string representation of an int quantity. </param> + /// <param name="radix"> The base to use for conversion. </param> + /// <returns> The value represented by the argument </returns> + /// <exception cref="FormatException"> If the argument could not be parsed as an int quantity. </exception> public static int ParseInt32(char[] chars, int offset, int len, int radix) { int minRadix = 2, maxRadix = 36; @@ -158,23 +158,22 @@ namespace Lucene.Net.Util */ /// <summary> - /// Returns an array size >= minTargetSize, generally - /// over-allocating exponentially to achieve amortized - /// linear-time cost as the array grows. - /// - /// NOTE: this was originally borrowed from Python 2.4.2 - /// listobject.c sources (attribution in LICENSE.txt), but - /// has now been substantially changed based on - /// discussions from java-dev thread with subject "Dynamic - /// array reallocation algorithms", started on Jan 12 - /// 2010. + /// Returns an array size >= <paramref name="minTargetSize"/>, generally + /// over-allocating exponentially to achieve amortized + /// linear-time cost as the array grows. + /// <para/> + /// NOTE: this was originally borrowed from Python 2.4.2 + /// listobject.c sources (attribution in LICENSE.txt), but + /// has now been substantially changed based on + /// discussions from java-dev thread with subject "Dynamic + /// array reallocation algorithms", started on Jan 12 + /// 2010. + /// <para/> + /// @lucene.internal /// </summary> /// <param name="minTargetSize"> Minimum required value to be returned. </param> /// <param name="bytesPerElement"> Bytes used by each element of - /// the array. See constants in <seealso cref="RamUsageEstimator"/>. - /// - /// @lucene.internal </param> - + /// the array. See constants in <see cref="RamUsageEstimator"/>. </param> public static int Oversize(int minTargetSize, int bytesPerElement) { if (minTargetSize < 0) @@ -661,9 +660,9 @@ namespace Lucene.Net.Util /// <param name="right"> The right array to compare </param> /// <param name="offsetRight"> the offset into the right array. Must be positive </param> /// <param name="length"> The length of the section of the array to compare </param> - /// <returns> true if the two arrays, starting at their respective offsets, are equal + /// <returns> <c>true</c> if the two arrays, starting at their respective offsets, are equal /// </returns> - /// <seealso cref= java.util.Arrays#equals(char[], char[]) </seealso> + /// <seealso cref="Support.Arrays.Equals{T}(T[], T[])"/> public static bool Equals(char[] left, int offsetLeft, char[] right, int offsetRight, int length) { if ((offsetLeft + length <= left.Length) && (offsetRight + length <= right.Length)) @@ -689,9 +688,9 @@ namespace Lucene.Net.Util /// <param name="right"> The right array to compare </param> /// <param name="offsetRight"> the offset into the right array. Must be positive </param> /// <param name="length"> The length of the section of the array to compare </param> - /// <returns> true if the two arrays, starting at their respective offsets, are equal + /// <returns> <c>true</c> if the two arrays, starting at their respective offsets, are equal /// </returns> - /// <seealso cref= java.util.Arrays#equals(byte[], byte[]) </seealso> + /// <seealso cref="Support.Arrays.Equals{T}(T[], T[])"/> public static bool Equals(byte[] left, int offsetLeft, byte[] right, int offsetRight, int length) { if ((offsetLeft + length <= left.Length) && (offsetRight + length <= right.Length)) @@ -746,9 +745,9 @@ namespace Lucene.Net.Util /// <param name="right"> The right array to compare </param> /// <param name="offsetRight"> the offset into the right array. Must be positive </param> /// <param name="length"> The length of the section of the array to compare </param> - /// <returns> true if the two arrays, starting at their respective offsets, are equal + /// <returns> <c>true</c> if the two arrays, starting at their respective offsets, are equal /// </returns> - /// <seealso cref= java.util.Arrays#equals(char[], char[]) </seealso> + /// <seealso cref="Support.Arrays.Equals{T}(T[], T[])"/> public static bool Equals(int[] left, int offsetLeft, int[] right, int offsetRight, int length) { if ((offsetLeft + length <= left.Length) && (offsetRight + length <= right.Length)) @@ -809,7 +808,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Get the natural <seealso cref="Comparer"/> for the provided object class. + /// Get the natural <see cref="IComparer{T}"/> for the provided object class. /// <para/> /// The comparer returned depends on the <typeparam name="T"/> argument: /// <list type="number"> @@ -849,7 +848,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Swap values stored in slots <code>i</code> and <code>j</code> </summary> + /// Swap values stored in slots <paramref name="i"/> and <paramref name="j"/> </summary> public static void Swap<T>(T[] arr, int i, int j) { T tmp = arr[i]; @@ -860,10 +859,10 @@ namespace Lucene.Net.Util // intro-sorts /// <summary> - /// Sorts the given array slice using the <seealso cref="Comparer"/>. this method uses the intro sort + /// Sorts the given array slice using the <see cref="IComparer{T}"/>. This method uses the intro sort /// algorithm, but falls back to insertion sort for small arrays. </summary> - /// <param name="fromIndex"> start index (inclusive) </param> - /// <param name="toIndex"> end index (exclusive) </param> + /// <param name="fromIndex"> Start index (inclusive) </param> + /// <param name="toIndex"> End index (exclusive) </param> public static void IntroSort<T>(T[] a, int fromIndex, int toIndex, IComparer<T> comp) { if (toIndex - fromIndex <= 1) @@ -874,7 +873,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Sorts the given array using the <seealso cref="Comparer"/>. this method uses the intro sort + /// Sorts the given array using the <see cref="IComparer{T}"/>. This method uses the intro sort /// algorithm, but falls back to insertion sort for small arrays. /// </summary> public static void IntroSort<T>(T[] a, IComparer<T> comp) @@ -883,10 +882,10 @@ namespace Lucene.Net.Util } /// <summary> - /// Sorts the given array slice in natural order. this method uses the intro sort + /// Sorts the given array slice in natural order. This method uses the intro sort /// algorithm, but falls back to insertion sort for small arrays. </summary> - /// <param name="fromIndex"> start index (inclusive) </param> - /// <param name="toIndex"> end index (exclusive) </param> + /// <param name="fromIndex"> Start index (inclusive) </param> + /// <param name="toIndex"> End index (exclusive) </param> public static void IntroSort<T>(T[] a, int fromIndex, int toIndex) //where T : IComparable<T> // LUCENENET specific: removing constraint because in .NET, it is not needed { if (toIndex - fromIndex <= 1) @@ -897,7 +896,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Sorts the given array in natural order. this method uses the intro sort + /// Sorts the given array in natural order. This method uses the intro sort /// algorithm, but falls back to insertion sort for small arrays. /// </summary> public static void IntroSort<T>(T[] a) //where T : IComparable<T> // LUCENENET specific: removing constraint because in .NET, it is not needed @@ -908,10 +907,10 @@ namespace Lucene.Net.Util // tim sorts: /// <summary> - /// Sorts the given array slice using the <seealso cref="Comparer"/>. this method uses the Tim sort + /// Sorts the given array slice using the <see cref="IComparer{T}"/>. This method uses the Tim sort /// algorithm, but falls back to binary sort for small arrays. </summary> - /// <param name="fromIndex"> start index (inclusive) </param> - /// <param name="toIndex"> end index (exclusive) </param> + /// <param name="fromIndex"> Start index (inclusive) </param> + /// <param name="toIndex"> End index (exclusive) </param> public static void TimSort<T>(T[] a, int fromIndex, int toIndex, IComparer<T> comp) { if (toIndex - fromIndex <= 1) @@ -922,7 +921,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Sorts the given array using the <seealso cref="Comparer"/>. this method uses the Tim sort + /// Sorts the given array using the <see cref="IComparer{T}"/>. this method uses the Tim sort /// algorithm, but falls back to binary sort for small arrays. /// </summary> public static void TimSort<T>(T[] a, IComparer<T> comp) @@ -933,8 +932,8 @@ namespace Lucene.Net.Util /// <summary> /// Sorts the given array slice in natural order. this method uses the Tim sort /// algorithm, but falls back to binary sort for small arrays. </summary> - /// <param name="fromIndex"> start index (inclusive) </param> - /// <param name="toIndex"> end index (exclusive) </param> + /// <param name="fromIndex"> Start index (inclusive) </param> + /// <param name="toIndex"> End index (exclusive) </param> public static void TimSort<T>(T[] a, int fromIndex, int toIndex) //where T : IComparable<T> // LUCENENET specific: removing constraint because in .NET, it is not needed { if (toIndex - fromIndex <= 1) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/AttributeImpl.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/AttributeImpl.cs b/src/Lucene.Net/Util/AttributeImpl.cs index 3afa263..4259bfa 100644 --- a/src/Lucene.Net/Util/AttributeImpl.cs +++ b/src/Lucene.Net/Util/AttributeImpl.cs @@ -25,7 +25,7 @@ namespace Lucene.Net.Util /// <summary> Base class for Attributes that can be added to a /// <see cref="Lucene.Net.Util.AttributeSource" />. - /// <p/> + /// <para/> /// Attributes are used to add data in a dynamic, yet type-safe way to a source /// of usually streamed objects, e. g. a <see cref="Lucene.Net.Analysis.TokenStream" />. /// </summary> @@ -37,14 +37,14 @@ namespace Lucene.Net.Util , ICloneable #endif { - /// <summary> Clears the values in this Attribute and resets it to its - /// default value. If this implementation implements more than one Attribute interface + /// <summary> Clears the values in this <see cref="Attribute"/> and resets it to its + /// default value. If this implementation implements more than one <see cref="Attribute"/> interface /// it clears all. /// </summary> public abstract void Clear(); /// <summary> - /// This is equivalent to the anonymous class in the java version of ReflectAsString + /// This is equivalent to the anonymous class in the Java version of ReflectAsString /// </summary> private class StringBuilderAttributeReflector : IAttributeReflector { @@ -77,6 +77,15 @@ namespace Lucene.Net.Util } } + /// <summary> + /// This method returns the current attribute values as a string in the following format + /// by calling the <see cref="ReflectWith(IAttributeReflector)"/> method: + /// <list type="bullet"> + /// <item><term>if <paramref name="prependAttClass"/>=true:</term> <description> <c>"AttributeClass.Key=value,AttributeClass.Key=value"</c> </description></item> + /// <item><term>if <paramref name="prependAttClass"/>=false:</term> <description> <c>"key=value,key=value"</c> </description></item> + /// </list> + /// </summary> + /// <seealso cref="ReflectWith(IAttributeReflector)"/> public string ReflectAsString(bool prependAttClass) { StringBuilder buffer = new StringBuilder(); @@ -86,6 +95,30 @@ namespace Lucene.Net.Util return buffer.ToString(); } + /// <summary> + /// This method is for introspection of attributes, it should simply + /// add the key/values this attribute holds to the given <see cref="IAttributeReflector"/>. + /// + /// <para/>The default implementation calls <see cref="IAttributeReflector.Reflect(Type, string, object)"/> for all + /// non-static fields from the implementing class, using the field name as key + /// and the field value as value. The <see cref="IAttribute"/> class is also determined by Reflection. + /// Please note that the default implementation can only handle single-Attribute + /// implementations. + /// + /// <para/>Custom implementations look like this (e.g. for a combined attribute implementation): + /// <code> + /// public void ReflectWith(IAttributeReflector reflector) + /// { + /// reflector.Reflect(typeof(ICharTermAttribute), "term", GetTerm()); + /// reflector.Reflect(typeof(IPositionIncrementAttribute), "positionIncrement", GetPositionIncrement()); + /// } + /// </code> + /// + /// <para/>If you implement this method, make sure that for each invocation, the same set of <see cref="IAttribute"/> + /// interfaces and keys are passed to <see cref="IAttributeReflector.Reflect(Type, string, object)"/> in the same order, but possibly + /// different values. So don't automatically exclude e.g. <c>null</c> properties! + /// </summary> + /// <seealso cref="ReflectAsString(bool)"/> public virtual void ReflectWith(IAttributeReflector reflector) // LUCENENET NOTE: This method was abstract in Lucene { Type clazz = this.GetType(); @@ -127,8 +160,9 @@ namespace Lucene.Net.Util /// fields of this object and prints the values in the following syntax: /// /// <code> - /// public String toString() { - /// return "start=" + startOffset + ",end=" + endOffset; + /// public String ToString() + /// { + /// return "start=" + startOffset + ",end=" + endOffset; /// } /// </code> /// @@ -163,9 +197,9 @@ namespace Lucene.Net.Util return buffer.ToString(); } - /// <summary> Copies the values from this Attribute into the passed-in - /// target attribute. The target implementation must support all the - /// Attributes this implementation supports. + /// <summary> Copies the values from this <see cref="Attribute"/> into the passed-in + /// <paramref name="target"/> attribute. The <paramref name="target"/> implementation must support all the + /// <see cref="IAttribute"/>s this implementation supports. /// </summary> public abstract void CopyTo(IAttribute target); http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/AttributeReflector.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/AttributeReflector.cs b/src/Lucene.Net/Util/AttributeReflector.cs new file mode 100644 index 0000000..9061886 --- /dev/null +++ b/src/Lucene.Net/Util/AttributeReflector.cs @@ -0,0 +1,42 @@ +using System; + +namespace Lucene.Net.Util +{ + /* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + /// <summary> + /// This interface is used to reflect contents of <see cref="AttributeSource"/> or <see cref="Attribute"/>. + /// </summary> + public interface IAttributeReflector + { + /// <summary> + /// LUCENENET specific overload to support generics. + /// </summary> + void Reflect<T>(string key, object value) + where T : IAttribute; + + /// <summary> + /// This method gets called for every property in an <see cref="Attribute"/>/<see cref="AttributeSource"/> + /// passing the <see cref="Type"/> of the <see cref="IAttribute"/>, a <paramref name="key"/> and the actual <paramref name="value"/>. + /// E.g., an invocation of <see cref="Analysis.TokenAttributes.CharTermAttribute.ReflectWith(IAttributeReflector)"/> + /// would call this method once using <see cref="T:typeof(Analysis.TokenAttributes.ICharTermAttribute)"/> + /// as attribute type, <c>"term"</c> as <paramref name="key"/> and the actual <paramref name="value"/> as a <see cref="string"/>. + /// </summary> + void Reflect(Type type, string key, object value); + } +} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/AttributeSource.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/AttributeSource.cs b/src/Lucene.Net/Util/AttributeSource.cs index 8c52d2e..ec80c40 100644 --- a/src/Lucene.Net/Util/AttributeSource.cs +++ b/src/Lucene.Net/Util/AttributeSource.cs @@ -27,11 +27,11 @@ namespace Lucene.Net.Util */ /// <summary> - /// An AttributeSource contains a list of different <seealso cref="Attribute"/>s, + /// An <see cref="AttributeSource"/> contains a list of different <see cref="Attribute"/>s, /// and methods to add and get them. There can only be a single instance - /// of an attribute in the same AttributeSource instance. this is ensured - /// by passing in the actual type of the Attribute (Class<Attribute>) to - /// the <seealso cref="#addAttribute(Class)"/>, which then checks if an instance of + /// of an attribute in the same <see cref="AttributeSource"/> instance. This is ensured + /// by passing in the actual type of the <see cref="IAttribute"/> to + /// the <see cref="AddAttribute{T}"/>, which then checks if an instance of /// that type is already present. If yes, it returns the instance, otherwise /// it creates a new instance and returns it. /// </summary> @@ -41,18 +41,18 @@ namespace Lucene.Net.Util public class AttributeSource { /// <summary> - /// An AttributeFactory creates instances of <seealso cref="Attribute"/>s. + /// An <see cref="AttributeFactory"/> creates instances of <see cref="Attribute"/>s. /// </summary> public abstract class AttributeFactory { /// <summary> - /// returns an <seealso cref="Attribute"/> for the supplied <seealso cref="Attribute"/> interface class. + /// returns an <see cref="Attribute"/> for the supplied <see cref="IAttribute"/> interface. /// </summary> public abstract Attribute CreateAttributeInstance<T>() where T : IAttribute; /// <summary> - /// this is the default factory that creates <seealso cref="Attribute"/>s using the - /// class name of the supplied <seealso cref="Attribute"/> interface class by appending <code>Impl</code> to it. + /// This is the default factory that creates <see cref="Attribute"/>s using the + /// <see cref="Type"/> of the supplied <see cref="IAttribute"/> interface by removing the <code>I</code> from the prefix. /// </summary> public static readonly AttributeFactory DEFAULT_ATTRIBUTE_FACTORY = new DefaultAttributeFactory(); @@ -101,9 +101,9 @@ namespace Lucene.Net.Util } /// <summary> - /// this class holds the state of an AttributeSource. </summary> - /// <seealso cref= #captureState </seealso> - /// <seealso cref= #restoreState </seealso> + /// This class holds the state of an <see cref="AttributeSource"/>. </summary> + /// <seealso cref="CaptureState()"/> + /// <seealso cref="RestoreState(State)"/> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -136,7 +136,7 @@ namespace Lucene.Net.Util private readonly AttributeFactory factory; /// <summary> - /// An AttributeSource using the default attribute factory <seealso cref="AttributeSource.AttributeFactory#DEFAULT_ATTRIBUTE_FACTORY"/>. + /// An <see cref="AttributeSource"/> using the default attribute factory <see cref="AttributeSource.AttributeFactory.DEFAULT_ATTRIBUTE_FACTORY"/>. /// </summary> public AttributeSource() : this(AttributeFactory.DEFAULT_ATTRIBUTE_FACTORY) @@ -144,7 +144,7 @@ namespace Lucene.Net.Util } /// <summary> - /// An AttributeSource that uses the same attributes as the supplied one. + /// An <see cref="AttributeSource"/> that uses the same attributes as the supplied one. /// </summary> public AttributeSource(AttributeSource input) { @@ -159,7 +159,7 @@ namespace Lucene.Net.Util } /// <summary> - /// An AttributeSource using the supplied <seealso cref="AttributeFactory"/> for creating new <seealso cref="Attribute"/> instances. + /// An <see cref="AttributeSource"/> using the supplied <see cref="AttributeFactory"/> for creating new <see cref="IAttribute"/> instances. /// </summary> public AttributeSource(AttributeFactory factory) { @@ -170,7 +170,7 @@ namespace Lucene.Net.Util } /// <summary> - /// returns the used AttributeFactory. + /// Returns the used <see cref="AttributeFactory"/>. /// </summary> public AttributeFactory GetAttributeFactory() { @@ -187,9 +187,9 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns a new iterator that iterates all unique Attribute implementations. - /// this iterator may contain less entries that <seealso cref="#getAttributeClassesIterator"/>, - /// if one instance implements more than one Attribute interface. + /// Returns a new iterator that iterates all unique <see cref="IAttribute"/> implementations. + /// This iterator may contain less entries than <see cref="GetAttributeClassesEnumerator()"/>, + /// if one instance implements more than one <see cref="IAttribute"/> interface. /// </summary> public IEnumerator<Attribute> GetAttributeImplsEnumerator() { @@ -260,7 +260,7 @@ namespace Lucene.Net.Util } /// <summary> - /// a cache that stores all interfaces for known implementation classes for performance (slow reflection) </summary> + /// A cache that stores all interfaces for known implementation classes for performance (slow reflection) </summary> private static readonly WeakIdentityMap<Type, LinkedList<WeakReference>> knownImplClasses = WeakIdentityMap<Type, LinkedList<WeakReference>>.NewConcurrentHashMap(false); @@ -294,13 +294,13 @@ namespace Lucene.Net.Util } /// <summary> - /// <b>Expert:</b> Adds a custom Attribute instance with one or more Attribute interfaces. - /// <p><font color="red"><b>Please note:</b> It is not guaranteed, that <code>att</code> is added to - /// the <code>AttributeSource</code>, because the provided attributes may already exist. - /// You should always retrieve the wanted attributes using <seealso cref="#getAttribute"/> after adding - /// with this method and cast to your class. - /// The recommended way to use custom implementations is using an <seealso cref="AttributeFactory"/>. - /// </font></p> + /// <b>Expert:</b> Adds a custom <see cref="Attribute"/> instance with one or more <see cref="IAttribute"/> interfaces. + /// <para><font color="red"><b>Please note:</b> It is not guaranteed, that <paramref name="att"/> is added to + /// the <see cref="AttributeSource"/>, because the provided attributes may already exist. + /// You should always retrieve the wanted attributes using <see cref="GetAttribute{T}"/> after adding + /// with this method and cast to your <see cref="Type"/>. + /// The recommended way to use custom implementations is using an <see cref="AttributeFactory"/>. + /// </font></para> /// </summary> public void AddAttributeImpl(Attribute att) { @@ -331,6 +331,12 @@ namespace Lucene.Net.Util } } + /// <summary> + /// The caller must pass in an interface type that extends <see cref="IAttribute"/>. + /// This method first checks if an instance of the corresponding class is + /// already in this <see cref="AttributeSource"/> and returns it. Otherwise a + /// new instance is created, added to this <see cref="AttributeSource"/> and returned. + /// </summary> public T AddAttribute<T>() where T : IAttribute { @@ -360,15 +366,15 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns true, iff this AttributeSource has any attributes </summary> + /// Returns <c>true</c>, if this <see cref="AttributeSource"/> has any attributes </summary> public bool HasAttributes { get { return this.attributes.Count > 0; } } /// <summary> - /// The caller must pass in a Class<? extends Attribute> value. - /// Returns true, iff this AttributeSource contains the passed-in Attribute. + /// The caller must pass in an interface type that extends <see cref="IAttribute"/>. + /// Returns <c>true</c>, if this <see cref="AttributeSource"/> contains the corrsponding <see cref="Attribute"/>. /// </summary> public bool HasAttribute<T>() where T : IAttribute { @@ -377,15 +383,15 @@ namespace Lucene.Net.Util } /// <summary> - /// The caller must pass in a Class<? extends Attribute> value. - /// Returns the instance of the passed in Attribute contained in this AttributeSource + /// The caller must pass in an interface type that extends <see cref="IAttribute"/>. + /// Returns the instance of the corresponding <see cref="Attribute"/> contained in this <see cref="AttributeSource"/> /// </summary> - /// <exception cref="IllegalArgumentException"> if this AttributeSource does not contain the - /// Attribute. It is recommended to always use <seealso cref="#addAttribute"/> even in consumers - /// of TokenStreams, because you cannot know if a specific TokenStream really uses - /// a specific Attribute. <seealso cref="#addAttribute"/> will automatically make the attribute + /// <exception cref="ArgumentException"> if this <see cref="AttributeSource"/> does not contain the + /// <see cref="Attribute"/>. It is recommended to always use <see cref="AddAttribute{T}()"/> even in consumers + /// of <see cref="Analysis.TokenStream"/>s, because you cannot know if a specific <see cref="Analysis.TokenStream"/> really uses + /// a specific <see cref="Attribute"/>. <see cref="AddAttribute{T}()"/> will automatically make the attribute /// available. If you want to only use the attribute, if it is available (to optimize - /// consuming), use <seealso cref="#HasAttribute"/>. </exception> + /// consuming), use <see cref="HasAttribute{T}()"/>. </exception> public virtual T GetAttribute<T>() where T : IAttribute { var attClass = typeof(T); @@ -417,8 +423,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Resets all Attributes in this AttributeSource by calling - /// <seealso cref="Attribute#clear()"/> on each Attribute implementation. + /// Resets all <see cref="Attribute"/>s in this <see cref="AttributeSource"/> by calling + /// <see cref="Attribute.Clear()"/> on each <see cref="IAttribute"/> implementation. /// </summary> public void ClearAttributes() { @@ -429,8 +435,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Captures the state of all Attributes. The return value can be passed to - /// <seealso cref="#restoreState"/> to restore the state of this or another AttributeSource. + /// Captures the state of all <see cref="Attribute"/>s. The return value can be passed to + /// <see cref="RestoreState(State)"/> to restore the state of this or another <see cref="AttributeSource"/>. /// </summary> public virtual State CaptureState() { @@ -443,15 +449,15 @@ namespace Lucene.Net.Util /// that this state contains into the attributes implementations of the targetStream. /// The targetStream must contain a corresponding instance for each argument /// contained in this state (e.g. it is not possible to restore the state of - /// an AttributeSource containing a TermAttribute into a AttributeSource using - /// a Token instance as implementation). - /// <p> + /// an <see cref="AttributeSource"/> containing a <see cref="Analysis.TokenAttributes.ICharTermAttribute"/> into a <see cref="AttributeSource"/> using + /// a <see cref="Analysis.Token"/> instance as implementation). + /// <para/> /// Note that this method does not affect attributes of the targetStream /// that are not contained in this state. In other words, if for example - /// the targetStream contains an OffsetAttribute, but this state doesn't, then - /// the value of the OffsetAttribute remains unchanged. It might be desirable to + /// the targetStream contains an <see cref="Analysis.TokenAttributes.IOffsetAttribute"/>, but this state doesn't, then + /// the value of the <see cref="Analysis.TokenAttributes.IOffsetAttribute"/> remains unchanged. It might be desirable to /// reset its value to the default, in which case the caller should first - /// call <seealso cref="TokenStream#ClearAttributes()"/> on the targetStream. + /// call <see cref="AttributeSource.ClearAttributes()"/> (<c>TokenStream.ClearAttributes()</c> on the targetStream. /// </summary> public void RestoreState(State state) { @@ -530,15 +536,15 @@ namespace Lucene.Net.Util } /// <summary> - /// this method returns the current attribute values as a string in the following format - /// by calling the <seealso cref="#reflectWith(AttributeReflector)"/> method: + /// This method returns the current attribute values as a string in the following format + /// by calling the <see cref="ReflectWith(IAttributeReflector)"/> method: /// - /// <ul> - /// <li><em>iff {@code prependAttClass=true}:</em> {@code "AttributeClass#key=value,AttributeClass#key=value"} - /// <li><em>iff {@code prependAttClass=false}:</em> {@code "key=value,key=value"} - /// </ul> + /// <list type="bullet"> + /// <item><term>if <paramref name="prependAttClass"/>=true:</term> <description> <c>"AttributeClass.Key=value,AttributeClass.Key=value"</c> </description></item> + /// <item><term>if <paramref name="prependAttClass"/>=false:</term> <description> <c>"key=value,key=value"</c> </description></item> + /// </list> /// </summary> - /// <seealso cref= #reflectWith(AttributeReflector) </seealso> + /// <seealso cref="ReflectWith(IAttributeReflector)"/> public string ReflectAsString(bool prependAttClass) { StringBuilder buffer = new StringBuilder(); @@ -581,13 +587,13 @@ namespace Lucene.Net.Util } /// <summary> - /// this method is for introspection of attributes, it should simply - /// add the key/values this AttributeSource holds to the given <seealso cref="AttributeReflector"/>. + /// This method is for introspection of attributes, it should simply + /// add the key/values this <see cref="AttributeSource"/> holds to the given <see cref="IAttributeReflector"/>. /// - /// <p>this method iterates over all Attribute implementations and calls the - /// corresponding <seealso cref="Attribute#reflectWith"/> method.</p> + /// <para>This method iterates over all <see cref="IAttribute"/> implementations and calls the + /// corresponding <see cref="Attribute.ReflectWith(IAttributeReflector)"/> method.</para> /// </summary> - /// <seealso cref= Attribute#reflectWith </seealso> + /// <seealso cref="Attribute.ReflectWith(IAttributeReflector)"/> public void ReflectWith(IAttributeReflector reflector) { for (State state = GetCurrentState(); state != null; state = state.next) @@ -597,10 +603,10 @@ namespace Lucene.Net.Util } /// <summary> - /// Performs a clone of all <seealso cref="Attribute"/> instances returned in a new - /// {@code AttributeSource} instance. this method can be used to e.g. create another TokenStream - /// with exactly the same attributes (using <seealso cref="#AttributeSource(AttributeSource)"/>). - /// You can also use it as a (non-performant) replacement for <seealso cref="#captureState"/>, if you need to look + /// Performs a clone of all <see cref="Attribute"/> instances returned in a new + /// <see cref="AttributeSource"/> instance. This method can be used to e.g. create another <see cref="Analysis.TokenStream"/> + /// with exactly the same attributes (using <see cref="AttributeSource(AttributeSource)"/>). + /// You can also use it as a (non-performant) replacement for <see cref="CaptureState()"/>, if you need to look /// into / modify the captured state. /// </summary> public AttributeSource CloneAttributes() @@ -632,12 +638,12 @@ namespace Lucene.Net.Util } /// <summary> - /// Copies the contents of this {@code AttributeSource} to the given target {@code AttributeSource}. - /// The given instance has to provide all <seealso cref="Attribute"/>s this instance contains. - /// The actual attribute implementations must be identical in both {@code AttributeSource} instances; - /// ideally both AttributeSource instances should use the same <seealso cref="AttributeFactory"/>. - /// You can use this method as a replacement for <seealso cref="#restoreState"/>, if you use - /// <seealso cref="#cloneAttributes"/> instead of <seealso cref="#captureState"/>. + /// Copies the contents of this <see cref="AttributeSource"/> to the given target <see cref="AttributeSource"/>. + /// The given instance has to provide all <see cref="IAttribute"/>s this instance contains. + /// The actual attribute implementations must be identical in both <see cref="AttributeSource"/> instances; + /// ideally both <see cref="AttributeSource"/> instances should use the same <see cref="AttributeFactory"/>. + /// You can use this method as a replacement for <see cref="RestoreState(State)"/>, if you use + /// <see cref="CloneAttributes()"/> instead of <see cref="CaptureState()"/>. /// </summary> public void CopyTo(AttributeSource target) { @@ -655,7 +661,7 @@ namespace Lucene.Net.Util /// <summary> /// Returns a string consisting of the class's simple name, the hex representation of the identity hash code, /// and the current reflection of all attributes. </summary> - /// <seealso cref= #reflectAsString(boolean) </seealso> + /// <seealso cref="ReflectAsString(bool)"/> public override string ToString() { return this.GetType().Name + '@' + RuntimeHelpers.GetHashCode(this).ToString("x") + " " + ReflectAsString(false); http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/BitUtil.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/BitUtil.cs b/src/Lucene.Net/Util/BitUtil.cs index 08fea44..dd1b81a 100644 --- a/src/Lucene.Net/Util/BitUtil.cs +++ b/src/Lucene.Net/Util/BitUtil.cs @@ -20,7 +20,8 @@ namespace Lucene.Net.Util // from org.apache.solr.util rev 555343 */ /// <summary> - /// A variety of high efficiency bit twiddling routines. + /// A variety of high efficiency bit twiddling routines. + /// <para/> /// @lucene.internal /// </summary> public sealed class BitUtil @@ -50,19 +51,20 @@ namespace Lucene.Net.Util // from org.apache.solr.util rev 555343 // should be faster than accessing an array for each index, and // the total array size is kept smaller (256*sizeof(int))=1K /// <summary> - ///*** the python code that generated bitlist + /// the python code that generated bitlist + /// <code> /// def bits2int(val): /// arr=0 /// for shift in range(8,0,-1): - /// if val & 0x80: - /// arr = (arr << 4) | shift - /// val = val << 1 + /// if val & 0x80: + /// arr = (arr << 4) | shift + /// val = val << 1 /// return arr /// /// def int_table(): /// tbl = [ hex(bits2int(val)).strip('L') for val in range(256) ] /// return ','.join(tbl) - /// ***** + /// </code> /// </summary> private static readonly int[] BIT_LISTS = new int[] { 0x0, 0x1, 0x2, 0x21, 0x3, 0x31, 0x32, 0x321, 0x4, 0x41, 0x42, 0x421, 0x43, @@ -100,21 +102,22 @@ namespace Lucene.Net.Util // from org.apache.solr.util rev 555343 } /// <summary> - /// Return the number of bits sets in b. </summary> + /// Return the number of bits sets in <paramref name="b"/>. </summary> public static int BitCount(byte b) { return BYTE_COUNTS[b & 0xFF]; } /// <summary> - /// Return the list of bits which are set in b encoded as followed: - /// <code>(i >>> (4 * n)) & 0x0F</code> is the offset of the n-th set bit of + /// Return the list of bits which are set in <paramref name="b"/> encoded as followed: + /// <code>(i >>> (4 * n)) & 0x0F</code> is the offset of the n-th set bit of /// the given byte plus one, or 0 if there are n or less bits set in the given - /// byte. For example <code>bitList(12)</code> returns 0x43:<ul> - /// <li><code>0x43 & 0x0F</code> is 3, meaning the the first bit set is at offset 3-1 = 2,</li> - /// <li><code>(0x43 >>> 4) & 0x0F</code> is 4, meaning there is a second bit set at offset 4-1=3,</li> - /// <li><code>(0x43 >>> 8) & 0x0F</code> is 0, meaning there is no more bit set in this byte.</li> - /// </ul> + /// byte. For example <code>bitList(12)</code> returns 0x43: + /// <list type="bullet"> + /// <item><description><code>0x43 & 0x0F</code> is 3, meaning the the first bit set is at offset 3-1 = 2,</description></item> + /// <item><description><code>(0x43 >>> 4) & 0x0F</code> is 4, meaning there is a second bit set at offset 4-1=3,</description></item> + /// <item><description><code>(0x43 >>> 8) & 0x0F</code> is 0, meaning there is no more bit set in this byte.</description></item> + /// </list> /// </summary> public static int BitList(byte b) { @@ -126,7 +129,7 @@ namespace Lucene.Net.Util // from org.apache.solr.util rev 555343 // intrinsic since Java 6u18) in a naive loop, see LUCENE-2221 /// <summary> - /// Returns the number of set bits in an array of longs. </summary> + /// Returns the number of set bits in an array of <see cref="long"/>s. </summary> public static long Pop_Array(long[] arr, int wordOffset, int numWords) { long popCount = 0; @@ -139,7 +142,7 @@ namespace Lucene.Net.Util // from org.apache.solr.util rev 555343 /// <summary> /// Returns the popcount or cardinality of the two sets after an intersection. - /// Neither array is modified. + /// Neither array is modified. /// </summary> public static long Pop_Intersect(long[] arr1, long[] arr2, int wordOffset, int numWords) { @@ -153,7 +156,7 @@ namespace Lucene.Net.Util // from org.apache.solr.util rev 555343 /// <summary> /// Returns the popcount or cardinality of the union of two sets. - /// Neither array is modified. + /// Neither array is modified. /// </summary> public static long Pop_Union(long[] arr1, long[] arr2, int wordOffset, int numWords) { @@ -166,8 +169,8 @@ namespace Lucene.Net.Util // from org.apache.solr.util rev 555343 } /// <summary> - /// Returns the popcount or cardinality of A & ~B. - /// Neither array is modified. + /// Returns the popcount or cardinality of A & ~B. + /// Neither array is modified. /// </summary> public static long Pop_AndNot(long[] arr1, long[] arr2, int wordOffset, int numWords) { @@ -194,7 +197,7 @@ namespace Lucene.Net.Util // from org.apache.solr.util rev 555343 } /// <summary> - /// returns the next highest power of two, or the current value if it's already a power of two or zero </summary> + /// Returns the next highest power of two, or the current value if it's already a power of two or zero </summary> public static int NextHighestPowerOfTwo(int v) { v--; @@ -208,7 +211,7 @@ namespace Lucene.Net.Util // from org.apache.solr.util rev 555343 } /// <summary> - /// returns the next highest power of two, or the current value if it's already a power of two or zero </summary> + /// Returns the next highest power of two, or the current value if it's already a power of two or zero </summary> public static long NextHighestPowerOfTwo(long v) { v--; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/Bits.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/Bits.cs b/src/Lucene.Net/Util/Bits.cs index fc7a256..d1cbcf9 100644 --- a/src/Lucene.Net/Util/Bits.cs +++ b/src/Lucene.Net/Util/Bits.cs @@ -19,17 +19,18 @@ namespace Lucene.Net.Util /// <summary> /// Interface for Bitset-like structures. + /// <para/> /// @lucene.experimental /// </summary> public interface IBits { /// <summary> - /// Returns the value of the bit with the specified <code>index</code>. + /// Returns the value of the bit with the specified <paramref name="index"/>. /// </summary> - /// <param name="index"> index, should be non-negative and < <seealso cref="#length()"/>. + /// <param name="index"> Index, should be non-negative and < <see cref="Length"/>. /// The result of passing negative or out of bounds values is undefined /// by this interface, <b>just don't do it!</b> </param> - /// <returns> <code>true</code> if the bit is set, <code>false</code> otherwise. </returns> + /// <returns> <c>true</c> if the bit is set, <c>false</c> otherwise. </returns> bool Get(int index); /// <summary> http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/BroadWord.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/BroadWord.cs b/src/Lucene.Net/Util/BroadWord.cs index 34864a4..3cc9b5c 100644 --- a/src/Lucene.Net/Util/BroadWord.cs +++ b/src/Lucene.Net/Util/BroadWord.cs @@ -23,14 +23,14 @@ namespace Lucene.Net.Util /// <summary> /// Methods and constants inspired by the article /// "Broadword Implementation of Rank/Select Queries" by Sebastiano Vigna, January 30, 2012: - /// <ul> - /// <li>algorithm 1: <seealso cref="#bitCount(long)"/>, count of set bits in a <code>long</code> - /// <li>algorithm 2: <seealso cref="#select(long, int)"/>, selection of a set bit in a <code>long</code>, - /// <li>bytewise signed smaller <<sub><small>8</small></sub> operator: <seealso cref="#smallerUpTo7_8(long,long)"/>. - /// <li>shortwise signed smaller <<sub><small>16</small></sub> operator: <seealso cref="#smallerUpto15_16(long,long)"/>. - /// <li>some of the Lk and Hk constants that are used by the above: - /// L8 <seealso cref="#L8_L"/>, H8 <seealso cref="#H8_L"/>, L9 <seealso cref="#L9_L"/>, L16 <seealso cref="#L16_L"/>and H16 <seealso cref="#H8_L"/>. - /// </ul> + /// <list type="bullet"> + /// <item><description>algorithm 1: <see cref="BitCount(long)"/>, count of set bits in a <see cref="long"/></description></item> + /// <item><description>algorithm 2: <see cref="Select(long, int)"/>, selection of a set bit in a <see cref="long"/>,</description></item> + /// <item><description>bytewise signed smaller <<sub><small>8</small></sub> operator: <see cref="SmallerUpTo7_8(long,long)"/>.</description></item> + /// <item><description>shortwise signed smaller <<sub><small>16</small></sub> operator: <see cref="SmallerUpto15_16(long,long)"/>.</description></item> + /// <item><description>some of the Lk and Hk constants that are used by the above: + /// L8 <see cref="L8_L"/>, H8 <see cref="H8_L"/>, L9 <see cref="L9_L"/>, L16 <see cref="L16_L"/>and H16 <see cref="H8_L"/>.</description></item> + /// </list> /// @lucene.internal /// </summary> public sealed class BroadWord @@ -41,9 +41,9 @@ namespace Lucene.Net.Util } /// <summary> - /// Bit count of a long. - /// Only here to compare the implementation with <seealso cref="#select(long,int)"/>, - /// normally <seealso cref="Long#bitCount"/> is preferable. </summary> + /// Bit count of a <see cref="long"/>. + /// Only here to compare the implementation with <see cref="Select(long, int)"/>, + /// normally <see cref="Number.BitCount(long)"/> is preferable. </summary> /// <returns> The total number of 1 bits in x. </returns> internal static int BitCount(long x) { @@ -58,7 +58,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Select a 1-bit from a long. </summary> + /// Select a 1-bit from a <see cref="long"/>. </summary> /// <returns> The index of the r-th 1 bit in x, or if no such bit exists, 72. </returns> public static int Select(long x, int r) { @@ -89,9 +89,9 @@ namespace Lucene.Net.Util } /// <summary> - /// A signed bytewise smaller <<sub><small>8</small></sub> operator, for operands 0L<= x, y <=0x7L. - /// this uses the following numbers of basic long operations: 1 or, 2 and, 2 xor, 1 minus, 1 not. </summary> - /// <returns> A long with bits set in the <seealso cref="#H8_L"/> positions corresponding to each input signed byte pair that compares smaller. </returns> + /// A signed bytewise smaller <<sub><small>8</small></sub> operator, for operands 0L<= x, y <=0x7L. + /// This uses the following numbers of basic <see cref="long"/> operations: 1 or, 2 and, 2 xor, 1 minus, 1 not. </summary> + /// <returns> A <see cref="long"/> with bits set in the <see cref="H8_L"/> positions corresponding to each input signed byte pair that compares smaller. </returns> public static long SmallerUpTo7_8(long x, long y) { // See section 4, page 5, line 14 of the Vigna article: @@ -100,8 +100,8 @@ namespace Lucene.Net.Util /// <summary> /// An unsigned bytewise smaller <<sub><small>8</small></sub> operator. - /// this uses the following numbers of basic long operations: 3 or, 2 and, 2 xor, 1 minus, 1 not. </summary> - /// <returns> A long with bits set in the <seealso cref="#H8_L"/> positions corresponding to each input unsigned byte pair that compares smaller. </returns> + /// This uses the following numbers of basic <see cref="long"/> operations: 3 or, 2 and, 2 xor, 1 minus, 1 not. </summary> + /// <returns> A <see cref="long"/> with bits set in the <see cref="H8_L"/> positions corresponding to each input unsigned byte pair that compares smaller. </returns> public static long Smalleru_8(long x, long y) { // See section 4, 8th line from the bottom of the page 5, of the Vigna article: @@ -110,8 +110,8 @@ namespace Lucene.Net.Util /// <summary> /// An unsigned bytewise not equals 0 operator. - /// this uses the following numbers of basic long operations: 2 or, 1 and, 1 minus. </summary> - /// <returns> A long with bits set in the <seealso cref="#H8_L"/> positions corresponding to each unsigned byte that does not equal 0. </returns> + /// This uses the following numbers of basic <see cref="long"/> operations: 2 or, 1 and, 1 minus. </summary> + /// <returns> A <see cref="long"/> with bits set in the <see cref="H8_L"/> positions corresponding to each unsigned byte that does not equal 0. </returns> public static long NotEquals0_8(long x) { // See section 4, line 6-8 on page 6, of the Vigna article: @@ -120,8 +120,8 @@ namespace Lucene.Net.Util /// <summary> /// A bytewise smaller <<sub><small>16</small></sub> operator. - /// this uses the following numbers of basic long operations: 1 or, 2 and, 2 xor, 1 minus, 1 not. </summary> - /// <returns> A long with bits set in the <seealso cref="#H16_L"/> positions corresponding to each input signed short pair that compares smaller. </returns> + /// This uses the following numbers of basic <see cref="long"/> operations: 1 or, 2 and, 2 xor, 1 minus, 1 not. </summary> + /// <returns> A <see cref="long"/> with bits set in the <see cref="H16_L"/> positions corresponding to each input signed short pair that compares smaller. </returns> public static long SmallerUpto15_16(long x, long y) { return (((x | H16_L) - (y & (~H16_L))) ^ x ^ ~y) & H16_L; @@ -129,8 +129,8 @@ namespace Lucene.Net.Util /// <summary> /// Lk denotes the constant whose ones are in position 0, k, 2k, . . . - /// These contain the low bit of each group of k bits. - /// The suffix _L indicates the long implementation. + /// These contain the low bit of each group of k bits. + /// The suffix _L indicates the <see cref="long"/> implementation. /// </summary> public const long L8_L = 0x0101010101010101L; @@ -138,16 +138,16 @@ namespace Lucene.Net.Util public const long L16_L = 0x0001000100010001L; /// <summary> - /// Hk = Lk << (k-1) . - /// These contain the high bit of each group of k bits. - /// The suffix _L indicates the long implementation. + /// Hk = Lk << (k-1) . + /// These contain the high bit of each group of k bits. + /// The suffix _L indicates the <see cref="long"/> implementation. /// </summary> public static readonly long H8_L = L8_L << 7; public static readonly long H16_L = L16_L << 15; /// <summary> - /// Naive implementation of <seealso cref="#select(long,int)"/>, using <seealso cref="Long#numberOfTrailingZeros"/> repetitively. + /// Naive implementation of <see cref="Select(long, int)"/>, using <see cref="Number.NumberOfLeadingZeros(long)"/> repetitively. /// Works relatively fast for low ranks. </summary> /// <returns> The index of the r-th 1 bit in x, or if no such bit exists, 72. </returns> public static int SelectNaive(long x, int r) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/ByteBlockPool.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/ByteBlockPool.cs b/src/Lucene.Net/Util/ByteBlockPool.cs index 5a1f0ae..58c13cd8 100644 --- a/src/Lucene.Net/Util/ByteBlockPool.cs +++ b/src/Lucene.Net/Util/ByteBlockPool.cs @@ -26,23 +26,22 @@ namespace Lucene.Net.Util /// <summary> /// Class that Posting and PostingVector use to write byte - /// streams into shared fixed-size byte[] arrays. The idea - /// is to allocate slices of increasing lengths For + /// streams into shared fixed-size <see cref="T:byte[]"/> arrays. The idea + /// is to allocate slices of increasing lengths. For /// example, the first slice is 5 bytes, the next slice is /// 14, etc. We start by writing our bytes into the first /// 5 bytes. When we hit the end of the slice, we allocate /// the next slice and then write the address of the new /// slice into the last 4 bytes of the previous slice (the /// "forwarding address"). - /// + /// <para/> /// Each slice is filled with 0's initially, and we mark - /// the end with a non-zero byte. this way the methods + /// the end with a non-zero byte. This way the methods /// that are writing into the slice don't need to record /// its length and instead allocate a new slice once they /// hit a non-zero byte. - /// + /// <para/> /// @lucene.internal - /// /// </summary> public sealed class ByteBlockPool { @@ -52,7 +51,7 @@ namespace Lucene.Net.Util /// <summary> /// Abstract class for allocating and freeing byte - /// blocks. + /// blocks. /// </summary> public abstract class Allocator { @@ -78,7 +77,7 @@ namespace Lucene.Net.Util } /// <summary> - /// A simple <seealso cref="Allocator"/> that never recycles. </summary> + /// A simple <see cref="Allocator"/> that never recycles. </summary> public sealed class DirectAllocator : Allocator { public DirectAllocator() @@ -97,8 +96,8 @@ namespace Lucene.Net.Util } /// <summary> - /// A simple <seealso cref="Allocator"/> that never recycles, but - /// tracks how much total RAM is in use. + /// A simple <see cref="Allocator"/> that never recycles, but + /// tracks how much total RAM is in use. /// </summary> public class DirectTrackingAllocator : Allocator { @@ -132,7 +131,7 @@ namespace Lucene.Net.Util } /// <summary> - /// array of buffers currently used in the pool. Buffers are allocated if + /// Array of buffers currently used in the pool. Buffers are allocated if /// needed don't modify this outside of this class. /// </summary> [WritableArray] @@ -181,9 +180,9 @@ namespace Lucene.Net.Util /// <summary> /// Resets the pool to its initial state reusing the first buffer and fills all - /// buffers with <tt>0</tt> bytes before they reused or passed to - /// <seealso cref="Allocator#recycleByteBlocks(byte[][], int, int)"/>. Calling - /// <seealso cref="ByteBlockPool#nextBuffer()"/> is not needed after reset. + /// buffers with <c>0</c> bytes before they reused or passed to + /// <see cref="Allocator.RecycleByteBlocks(byte[][], int, int)"/>. Calling + /// <see cref="ByteBlockPool.NextBuffer()"/> is not needed after reset. /// </summary> public void Reset() { @@ -192,12 +191,12 @@ namespace Lucene.Net.Util /// <summary> /// Expert: Resets the pool to its initial state reusing the first buffer. Calling - /// <seealso cref="ByteBlockPool#nextBuffer()"/> is not needed after reset. </summary> - /// <param name="zeroFillBuffers"> if <code>true</code> the buffers are filled with <tt>0</tt>. - /// this should be set to <code>true</code> if this pool is used with slices. </param> - /// <param name="reuseFirst"> if <code>true</code> the first buffer will be reused and calling - /// <seealso cref="ByteBlockPool#nextBuffer()"/> is not needed after reset iff the - /// block pool was used before ie. <seealso cref="ByteBlockPool#nextBuffer()"/> was called before. </param> + /// <see cref="ByteBlockPool.NextBuffer()"/> is not needed after reset. </summary> + /// <param name="zeroFillBuffers"> if <c>true</c> the buffers are filled with <tt>0</tt>. + /// this should be set to <c>true</c> if this pool is used with slices. </param> + /// <param name="reuseFirst"> if <c>true</c> the first buffer will be reused and calling + /// <see cref="ByteBlockPool.NextBuffer()"/> is not needed after reset if the + /// block pool was used before ie. <see cref="ByteBlockPool.NextBuffer()"/> was called before. </param> public void Reset(bool zeroFillBuffers, bool reuseFirst) { if (bufferUpto != -1) @@ -209,11 +208,9 @@ namespace Lucene.Net.Util for (int i = 0; i < bufferUpto; i++) { // Fully zero fill buffers that we fully used - //Array.Clear(Buffers[i], 0, Buffers[i].Length); Arrays.Fill(buffers[i], (byte)0); } // Partial zero fill the final buffer - //Array.Clear(Buffers[BufferUpto], 0, BufferUpto); Arrays.Fill(buffers[bufferUpto], 0, ByteUpto, (byte)0); } @@ -222,7 +219,6 @@ namespace Lucene.Net.Util int offset = reuseFirst ? 1 : 0; // Recycle all but the first buffer allocator.RecycleByteBlocks(buffers, offset, 1 + bufferUpto); - //Array.Clear(Buffers, 0, Buffers.Length); Arrays.Fill(buffers, offset, 1 + bufferUpto, null); } if (reuseFirst) @@ -244,9 +240,9 @@ namespace Lucene.Net.Util } /// <summary> - /// Advances the pool to its next buffer. this method should be called once + /// Advances the pool to its next buffer. This method should be called once /// after the constructor to initialize the pool. In contrast to the - /// constructor a <seealso cref="ByteBlockPool#reset()"/> call will advance the pool to + /// constructor a <see cref="ByteBlockPool.Reset()"/> call will advance the pool to /// its first buffer immediately. /// </summary> public void NextBuffer() @@ -266,7 +262,7 @@ namespace Lucene.Net.Util /// <summary> /// Allocates a new slice with the given size.</summary> - /// <seealso>ByteBlockPool#FIRST_LEVEL_SIZE</seealso> + /// <seealso cref="ByteBlockPool.FIRST_LEVEL_SIZE"/> public int NewSlice(int size) { if (ByteUpto > BYTE_BLOCK_SIZE - size) @@ -286,7 +282,7 @@ namespace Lucene.Net.Util // bytes, next slice is 14 bytes, etc. /// <summary> - /// An array holding the offset into the <seealso cref="ByteBlockPool#LEVEL_SIZE_ARRAY"/> + /// An array holding the offset into the <see cref="ByteBlockPool.LEVEL_SIZE_ARRAY"/> /// to quickly navigate to the next slice level. /// </summary> public static readonly int[] NEXT_LEVEL_ARRAY = new int[] { 1, 2, 3, 4, 5, 6, 7, 8, 9, 9 }; @@ -298,7 +294,7 @@ namespace Lucene.Net.Util /// <summary> /// The first level size for new slices </summary> - /// <seealso cref= ByteBlockPool#newSlice(int) </seealso> + /// <seealso cref="ByteBlockPool.NewSlice(int)"/> public static readonly int FIRST_LEVEL_SIZE = LEVEL_SIZE_ARRAY[0]; /// <summary> @@ -361,7 +357,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Appends the bytes in the provided <seealso cref="BytesRef"/> at + /// Appends the bytes in the provided <see cref="BytesRef"/> at /// the current position. /// </summary> public void Append(BytesRef bytes) @@ -398,8 +394,8 @@ namespace Lucene.Net.Util /// <summary> /// Reads bytes bytes out of the pool starting at the given offset with the given - /// length into the given byte array at offset <tt>off</tt>. - /// <p>Note: this method allows to copy across block boundaries.</p> + /// length into the given byte array at offset <c>off</c>. + /// <para>Note: this method allows to copy across block boundaries.</para> /// </summary> public void ReadBytes(long offset, byte[] bytes, int off, int length) { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/BytesRef.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/BytesRef.cs b/src/Lucene.Net/Util/BytesRef.cs index 2530231..624bda5 100644 --- a/src/Lucene.Net/Util/BytesRef.cs +++ b/src/Lucene.Net/Util/BytesRef.cs @@ -25,14 +25,14 @@ namespace Lucene.Net.Util */ /// <summary> - /// Represents byte[], as a slice (offset + length) into an - /// existing byte[]. The <seealso cref="#bytes"/> member should never be null; - /// use <seealso cref="#EMPTY_BYTES"/> if necessary. + /// Represents <see cref="T:byte[]"/>, as a slice (offset + length) into an + /// existing <see cref="T:byte[]"/>. The <see cref="Bytes"/> property should never be <c>null</c>; + /// use <see cref="EMPTY_BYTES"/> if necessary. /// - /// <p><b>Important note:</b> Unless otherwise noted, Lucene uses this class to + /// <para/><b>Important note:</b> Unless otherwise noted, Lucene uses this class to /// represent terms that are encoded as <b>UTF8</b> bytes in the index. To - /// convert them to a Java <seealso cref="String"/> (which is UTF16), use <seealso cref="#utf8ToString"/>. - /// Using code like {@code new String(bytes, offset, length)} to do this + /// convert them to a .NET <see cref="string"/> (which is UTF16), use <see cref="Utf8ToString()"/>. + /// Using code like <c>new String(bytes, offset, length)</c> to do this /// is <b>wrong</b>, as it does not respect the correct character set /// and may return wrong results (depending on the platform's defaults)! /// </summary> @@ -46,7 +46,7 @@ namespace Lucene.Net.Util public static readonly byte[] EMPTY_BYTES = new byte[0]; /// <summary> - /// The contents of the BytesRef. Should never be {@code null}. + /// The contents of the BytesRef. Should never be <c>null</c>. /// </summary> [WritableArray] [SuppressMessage("Microsoft.Performance", "CA1819", Justification = "Lucene's design requires some writable array properties")] @@ -68,15 +68,15 @@ namespace Lucene.Net.Util public int Length { get; set; } /// <summary> - /// Create a BytesRef with <seealso cref="#EMPTY_BYTES"/> </summary> + /// Create a <see cref="BytesRef"/> with <see cref="EMPTY_BYTES"/> </summary> public BytesRef() : this(EMPTY_BYTES) { } /// <summary> - /// this instance will directly reference bytes w/o making a copy. - /// bytes should not be null. + /// This instance will directly reference <paramref name="bytes"/> w/o making a copy. + /// <paramref name="bytes"/> should not be <c>null</c>. /// </summary> public BytesRef(byte[] bytes, int offset, int length) { @@ -87,8 +87,8 @@ namespace Lucene.Net.Util } /// <summary> - /// this instance will directly reference bytes w/o making a copy. - /// bytes should not be null + /// This instance will directly reference <paramref name="bytes"/> w/o making a copy. + /// <paramref name="bytes"/> should not be <c>null</c>. /// </summary> public BytesRef(byte[] bytes) : this(bytes, 0, bytes.Length) @@ -96,7 +96,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Create a BytesRef pointing to a new array of size <code>capacity</code>. + /// Create a <see cref="BytesRef"/> pointing to a new array of size <paramref name="capacity"/>. /// Offset and length will both be zero. /// </summary> public BytesRef(int capacity) @@ -105,10 +105,10 @@ namespace Lucene.Net.Util } /// <summary> - /// Initialize the byte[] from the UTF8 bytes - /// for the provided String. + /// Initialize the <see cref="T:byte[]"/> from the UTF8 bytes + /// for the provided <see cref="ICharSequence"/>. /// </summary> - /// <param name="text"> this must be well-formed + /// <param name="text"> This must be well-formed /// unicode text, with no unpaired surrogates. </param> public BytesRef(ICharSequence text) : this() @@ -117,10 +117,10 @@ namespace Lucene.Net.Util } /// <summary> - /// Initialize the byte[] from the UTF8 bytes - /// for the provided String. + /// Initialize the <see cref="T:byte[]"/> from the UTF8 bytes + /// for the provided <see cref="string"/>. /// </summary> - /// <param name="text"> this must be well-formed + /// <param name="text"> This must be well-formed /// unicode text, with no unpaired surrogates. </param> public BytesRef(string text) : this() @@ -129,7 +129,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Copies the UTF8 bytes for this string. + /// Copies the UTF8 bytes for this <see cref="ICharSequence"/>. /// </summary> /// <param name="text"> Must be well-formed unicode text, with no /// unpaired surrogates or invalid UTF16 code units. </param> @@ -140,7 +140,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Copies the UTF8 bytes for this string. + /// Copies the UTF8 bytes for this <see cref="string"/>. /// </summary> /// <param name="text"> Must be well-formed unicode text, with no /// unpaired surrogates or invalid UTF16 code units. </param> @@ -151,11 +151,12 @@ namespace Lucene.Net.Util } /// <summary> - /// Expert: compares the bytes against another BytesRef, - /// returning true if the bytes are equal. + /// Expert: Compares the bytes against another <see cref="BytesRef"/>, + /// returning <c>true</c> if the bytes are equal. + /// <para/> + /// @lucene.internal /// </summary> - /// <param name="other"> Another BytesRef, should not be null. - /// @lucene.internal </param> + /// <param name="other"> Another <see cref="BytesRef"/>, should not be <c>null</c>. </param> public bool BytesEquals(BytesRef other) { Debug.Assert(other != null); @@ -184,18 +185,18 @@ namespace Lucene.Net.Util /// <b>not</b> copied and will be shared by both the returned object and this /// object. /// </summary> - /// <seealso cref= #deepCopyOf </seealso> + /// <seealso cref="DeepCopyOf(BytesRef)"/> public object Clone() { return new BytesRef(bytes, Offset, Length); } /// <summary> - /// Calculates the hash code as required by TermsHash during indexing. - /// <p> this is currently implemented as MurmurHash3 (32 - /// bit), using the seed from {@link - /// StringHelper#GOOD_FAST_HASH_SEED}, but is subject to - /// change from release to release. + /// Calculates the hash code as required by <see cref="Index.TermsHash"/> during indexing. + /// <para/> This is currently implemented as MurmurHash3 (32 + /// bit), using the seed from + /// <see cref="StringHelper.GOOD_FAST_HASH_SEED"/>, but is subject to + /// change from release to release. /// </summary> public override int GetHashCode() { @@ -217,7 +218,7 @@ namespace Lucene.Net.Util /// <summary> /// Interprets stored bytes as UTF8 bytes, returning the - /// resulting string + /// resulting <see cref="string"/>. /// </summary> public string Utf8ToString() { @@ -246,8 +247,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Copies the bytes from the given <seealso cref="BytesRef"/> - /// <p> + /// Copies the bytes from the given <see cref="BytesRef"/> + /// <para/> /// NOTE: if this would exceed the array size, this method creates a /// new reference array. /// </summary> @@ -263,8 +264,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Appends the bytes from the given <seealso cref="BytesRef"/> - /// <p> + /// Appends the bytes from the given <see cref="BytesRef"/> + /// <para/> /// NOTE: if this would exceed the array size, this method creates a /// new reference array. /// </summary> @@ -284,8 +285,9 @@ namespace Lucene.Net.Util /// <summary> /// Used to grow the reference array. - /// + /// <para/> /// In general this should not be used as it does not take the offset into account. + /// <para/> /// @lucene.internal /// </summary> public void Grow(int newLength) @@ -338,13 +340,13 @@ namespace Lucene.Net.Util // LUCENENET NOTE: De-nested Utf8SortedAsUtf16Comparer class to prevent naming conflict - + /// <summary> - /// Creates a new BytesRef that points to a copy of the bytes from - /// <code>other</code> - /// <p> - /// The returned BytesRef will have a length of other.length + /// Creates a new <see cref="BytesRef"/> that points to a copy of the bytes from + /// <paramref name="other"/>. + /// <para/> + /// The returned <see cref="BytesRef"/> will have a length of <c>other.Length</c> /// and an offset of zero. /// </summary> public static BytesRef DeepCopyOf(BytesRef other) @@ -356,7 +358,7 @@ namespace Lucene.Net.Util /// <summary> /// Performs internal consistency checks. - /// Always returns true (or throws InvalidOperationException) + /// Always returns true (or throws <see cref="InvalidOperationException"/>) /// </summary> public bool IsValid() {
