You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucenenet.apache.org by ni...@apache.org on 2017/06/06 00:11:48 UTC
[15/48] lucenenet git commit: Lucene.Net.Util: Fixed up documentation
comments, types beginning with A-G
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/BytesRefArray.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/BytesRefArray.cs b/src/Lucene.Net/Util/BytesRefArray.cs
index 309e9d8..c6f16ef 100644
--- a/src/Lucene.Net/Util/BytesRefArray.cs
+++ b/src/Lucene.Net/Util/BytesRefArray.cs
@@ -22,12 +22,11 @@ namespace Lucene.Net.Util
*/
/// <summary>
- /// A simple append only random-access <seealso cref="BytesRef"/> array that stores full
- /// copies of the appended bytes in a <seealso cref="ByteBlockPool"/>.
- ///
- ///
+ /// A simple append only random-access <see cref="BytesRef"/> array that stores full
+ /// copies of the appended bytes in a <see cref="ByteBlockPool"/>.
+ /// <para/>
/// <b>Note: this class is not Thread-Safe!</b>
- ///
+ /// <para/>
/// @lucene.internal
/// @lucene.experimental
/// </summary>
@@ -43,7 +42,7 @@ namespace Lucene.Net.Util
private readonly Counter bytesUsed;
/// <summary>
- /// Creates a new <seealso cref="BytesRefArray"/> with a counter to track allocated bytes
+ /// Creates a new <see cref="BytesRefArray"/> with a counter to track allocated bytes
/// </summary>
public BytesRefArray(Counter bytesUsed)
{
@@ -54,7 +53,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Clears this <seealso cref="BytesRefArray"/>
+ /// Clears this <see cref="BytesRefArray"/>
/// </summary>
public void Clear()
{
@@ -65,9 +64,9 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Appends a copy of the given <seealso cref="BytesRef"/> to this <seealso cref="BytesRefArray"/>. </summary>
- /// <param name="bytes"> the bytes to append </param>
- /// <returns> the index of the appended bytes </returns>
+ /// Appends a copy of the given <see cref="BytesRef"/> to this <see cref="BytesRefArray"/>. </summary>
+ /// <param name="bytes"> The bytes to append </param>
+ /// <returns> The index of the appended bytes </returns>
public int Append(BytesRef bytes)
{
if (lastElement >= offsets.Length)
@@ -84,19 +83,20 @@ namespace Lucene.Net.Util
/// <summary>
/// Returns the current size of this <see cref="BytesRefArray"/>.
+ /// <para/>
/// NOTE: This was size() in Lucene.
/// </summary>
- /// <returns> the current size of this <see cref="BytesRefArray"/> </returns>
+ /// <returns> The current size of this <see cref="BytesRefArray"/> </returns>
public int Length
{
get { return lastElement; }
}
/// <summary>
- /// Returns the <i>n'th</i> element of this <seealso cref="BytesRefArray"/> </summary>
- /// <param name="spare"> a spare <seealso cref="BytesRef"/> instance </param>
- /// <param name="index"> the elements index to retrieve </param>
- /// <returns> the <i>n'th</i> element of this <seealso cref="BytesRefArray"/> </returns>
+ /// Returns the <i>n'th</i> element of this <see cref="BytesRefArray"/> </summary>
+ /// <param name="spare"> A spare <see cref="BytesRef"/> instance </param>
+ /// <param name="index"> The elements index to retrieve </param>
+ /// <returns> The <i>n'th</i> element of this <see cref="BytesRefArray"/> </returns>
public BytesRef Get(BytesRef spare, int index)
{
if (lastElement > index)
@@ -171,7 +171,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// sugar for <seealso cref="#iterator(Comparer)"/> with a <code>null</code> comparer
+ /// Sugar for <see cref="GetIterator(IComparer{BytesRef})"/> with a <c>null</c> comparer
/// </summary>
public IBytesRefIterator GetIterator()
{
@@ -179,18 +179,18 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// <p>
- /// Returns a <seealso cref="IBytesRefIterator"/> with point in time semantics. The
- /// iterator provides access to all so far appended <seealso cref="BytesRef"/> instances.
- /// </p>
- /// <p>
- /// If a non <code>null</code> <seealso cref="Comparer"/> is provided the iterator will
+ /// <para>
+ /// Returns a <see cref="IBytesRefIterator"/> with point in time semantics. The
+ /// iterator provides access to all so far appended <see cref="BytesRef"/> instances.
+ /// </para>
+ /// <para>
+ /// If a non <c>null</c> <see cref="T:IComparer{BytesRef}"/> is provided the iterator will
/// iterate the byte values in the order specified by the comparer. Otherwise
/// the order is the same as the values were appended.
- /// </p>
- /// <p>
- /// this is a non-destructive operation.
- /// </p>
+ /// </para>
+ /// <para>
+ /// This is a non-destructive operation.
+ /// </para>
/// </summary>
public IBytesRefIterator GetIterator(IComparer<BytesRef> comp)
{
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/BytesRefHash.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/BytesRefHash.cs b/src/Lucene.Net/Util/BytesRefHash.cs
index 6c8a839..4ad61d6 100644
--- a/src/Lucene.Net/Util/BytesRefHash.cs
+++ b/src/Lucene.Net/Util/BytesRefHash.cs
@@ -28,18 +28,18 @@ namespace Lucene.Net.Util
using DirectAllocator = Lucene.Net.Util.ByteBlockPool.DirectAllocator;
/// <summary>
- /// <seealso cref="BytesRefHash"/> is a special purpose hash-map like data-structure
- /// optimized for <seealso cref="BytesRef"/> instances. BytesRefHash maintains mappings of
+ /// <see cref="BytesRefHash"/> is a special purpose hash-map like data-structure
+ /// optimized for <see cref="BytesRef"/> instances. <see cref="BytesRefHash"/> maintains mappings of
/// byte arrays to ids (Map<BytesRef,int>) storing the hashed bytes
/// efficiently in continuous storage. The mapping to the id is
- /// encapsulated inside <seealso cref="BytesRefHash"/> and is guaranteed to be increased
- /// for each added <seealso cref="BytesRef"/>.
+ /// encapsulated inside <see cref="BytesRefHash"/> and is guaranteed to be increased
+ /// for each added <see cref="BytesRef"/>.
///
- /// <p>
- /// Note: The maximum capacity <seealso cref="BytesRef"/> instance passed to
- /// <seealso cref="#add(BytesRef)"/> must not be longer than <seealso cref="ByteBlockPool#BYTE_BLOCK_SIZE"/>-2.
+ /// <para>
+ /// Note: The maximum capacity <see cref="BytesRef"/> instance passed to
+ /// <see cref="Add(BytesRef)"/> must not be longer than <see cref="ByteBlockPool.BYTE_BLOCK_SIZE"/>-2.
/// The internal storage is limited to 2GB total byte storage.
- /// </p>
+ /// </para>
///
/// @lucene.internal
/// </summary>
@@ -64,8 +64,8 @@ namespace Lucene.Net.Util
private Counter bytesUsed;
/// <summary>
- /// Creates a new <seealso cref="BytesRefHash"/> with a <seealso cref="ByteBlockPool"/> using a
- /// <seealso cref="DirectAllocator"/>.
+ /// Creates a new <see cref="BytesRefHash"/> with a <see cref="ByteBlockPool"/> using a
+ /// <see cref="DirectAllocator"/>.
/// </summary>
public BytesRefHash()
: this(new ByteBlockPool(new DirectAllocator()))
@@ -73,7 +73,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Creates a new <seealso cref="BytesRefHash"/>
+ /// Creates a new <see cref="BytesRefHash"/>
/// </summary>
public BytesRefHash(ByteBlockPool pool)
: this(pool, DEFAULT_CAPACITY, new DirectBytesStartArray(DEFAULT_CAPACITY))
@@ -81,7 +81,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Creates a new <seealso cref="BytesRefHash"/>
+ /// Creates a new <see cref="BytesRefHash"/>
/// </summary>
public BytesRefHash(ByteBlockPool pool, int capacity, BytesStartArray bytesStartArray)
{
@@ -98,28 +98,29 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Returns the number of <seealso cref="BytesRef"/> values in this <seealso cref="BytesRefHash"/>.
+ /// Returns the number of <see cref="BytesRef"/> values in this <see cref="BytesRefHash"/>.
+ /// <para/>
/// NOTE: This was size() in Lucene.
/// </summary>
- /// <returns> the number of <seealso cref="BytesRef"/> values in this <seealso cref="BytesRefHash"/>. </returns>
+ /// <returns> The number of <see cref="BytesRef"/> values in this <see cref="BytesRefHash"/>. </returns>
public int Count
{
get { return count; }
}
/// <summary>
- /// Populates and returns a <seealso cref="BytesRef"/> with the bytes for the given
+ /// Populates and returns a <see cref="BytesRef"/> with the bytes for the given
/// bytesID.
- /// <p>
+ /// <para/>
/// Note: the given bytesID must be a positive integer less than the current
- /// size (<seealso cref="Count"/>)
+ /// size (<see cref="Count"/>)
/// </summary>
/// <param name="bytesID">
- /// the id </param>
+ /// The id </param>
/// <param name="ref">
- /// the <seealso cref="BytesRef"/> to populate
+ /// The <see cref="BytesRef"/> to populate
/// </param>
- /// <returns> the given BytesRef instance populated with the bytes for the given
+ /// <returns> The given <see cref="BytesRef"/> instance populated with the bytes for the given
/// bytesID </returns>
public BytesRef Get(int bytesID, BytesRef @ref)
{
@@ -131,11 +132,11 @@ namespace Lucene.Net.Util
/// <summary>
/// Returns the ids array in arbitrary order. Valid ids start at offset of 0
- /// and end at a limit of <seealso cref="Count"/> - 1
- /// <p>
- /// Note: this is a destructive operation. <seealso cref="#clear()"/> must be called in
- /// order to reuse this <seealso cref="BytesRefHash"/> instance.
- /// </p>
+ /// and end at a limit of <see cref="Count"/> - 1
+ /// <para>
+ /// Note: this is a destructive operation. <see cref="Clear()"/> must be called in
+ /// order to reuse this <see cref="BytesRefHash"/> instance.
+ /// </para>
/// </summary>
public int[] Compact()
{
@@ -161,13 +162,13 @@ namespace Lucene.Net.Util
/// <summary>
/// Returns the values array sorted by the referenced byte values.
- /// <p>
- /// Note: this is a destructive operation. <seealso cref="#clear()"/> must be called in
- /// order to reuse this <seealso cref="BytesRefHash"/> instance.
- /// </p>
+ /// <para>
+ /// Note: this is a destructive operation. <see cref="Clear()"/> must be called in
+ /// order to reuse this <see cref="BytesRefHash"/> instance.
+ /// </para>
/// </summary>
/// <param name="comp">
- /// the <seealso cref="Comparer"/> used for sorting </param>
+ /// The <see cref="T:IComparer{BytesRef}"/> used for sorting </param>
public int[] Sort(IComparer<BytesRef> comp)
{
int[] compact = Compact();
@@ -254,7 +255,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Clears the <seealso cref="BytesRef"/> which maps to the given <seealso cref="BytesRef"/>
+ /// Clears the <see cref="BytesRef"/> which maps to the given <see cref="BytesRef"/>
/// </summary>
public void Clear(bool resetPool)
{
@@ -279,7 +280,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Closes the BytesRefHash and releases all internally used memory
+ /// Closes the <see cref="BytesRefHash"/> and releases all internally used memory
/// </summary>
public void Dispose()
{
@@ -289,18 +290,18 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Adds a new <seealso cref="BytesRef"/>
+ /// Adds a new <see cref="BytesRef"/>
/// </summary>
/// <param name="bytes">
- /// the bytes to hash </param>
- /// <returns> the id the given bytes are hashed if there was no mapping for the
- /// given bytes, otherwise <code>(-(id)-1)</code>. this guarantees
+ /// The bytes to hash </param>
+ /// <returns> The id the given bytes are hashed if there was no mapping for the
+ /// given bytes, otherwise <c>(-(id)-1)</c>. this guarantees
/// that the return value will always be >= 0 if the given bytes
/// haven't been hashed before.
/// </returns>
/// <exception cref="MaxBytesLengthExceededException">
/// if the given bytes are > 2 +
- /// <seealso cref="ByteBlockPool#BYTE_BLOCK_SIZE"/> </exception>
+ /// <see cref="ByteBlockPool.BYTE_BLOCK_SIZE"/> </exception>
public int Add(BytesRef bytes)
{
Debug.Assert(bytesStart != null, "Bytesstart is null - not initialized");
@@ -365,12 +366,12 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Returns the id of the given <seealso cref="BytesRef"/>.
+ /// Returns the id of the given <see cref="BytesRef"/>.
/// </summary>
/// <param name="bytes">
- /// the bytes to look for
+ /// The bytes to look for
/// </param>
- /// <returns> the id of the given bytes, or {@code -1} if there is no mapping for the
+ /// <returns> The id of the given bytes, or <c>-1</c> if there is no mapping for the
/// given bytes. </returns>
public int Find(BytesRef bytes)
{
@@ -402,12 +403,12 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Adds a "arbitrary" int offset instead of a BytesRef
- /// term. this is used in the indexer to hold the hash for term
- /// vectors, because they do not redundantly store the byte[] term
- /// directly and instead reference the byte[] term
- /// already stored by the postings BytesRefHash. See
- /// add(int textStart) in TermsHashPerField.
+ /// Adds a "arbitrary" int offset instead of a <see cref="BytesRef"/>
+ /// term. This is used in the indexer to hold the hash for term
+ /// vectors, because they do not redundantly store the <see cref="T:byte[]"/> term
+ /// directly and instead reference the <see cref="T:byte[]"/> term
+ /// already stored by the postings <see cref="BytesRefHash"/>. See
+ /// <see cref="Index.TermsHashPerField.Add(int)"/>.
/// </summary>
public int AddByPoolOffset(int offset)
{
@@ -450,7 +451,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Called when hash is too small (> 50% occupied) or too large (< 20%
+ /// Called when hash is too small (> 50% occupied) or too large (< 20%
/// occupied).
/// </summary>
private void Rehash(int newSize, bool hashOnData)
@@ -520,8 +521,8 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// reinitializes the <seealso cref="BytesRefHash"/> after a previous <seealso cref="#clear()"/>
- /// call. If <seealso cref="#clear()"/> has not been called previously this method has no
+ /// Reinitializes the <see cref="BytesRefHash"/> after a previous <see cref="Clear()"/>
+ /// call. If <see cref="Clear()"/> has not been called previously this method has no
/// effect.
/// </summary>
public void Reinit()
@@ -540,12 +541,12 @@ namespace Lucene.Net.Util
/// <summary>
/// Returns the bytesStart offset into the internally used
- /// <seealso cref="ByteBlockPool"/> for the given bytesID
+ /// <see cref="ByteBlockPool"/> for the given <paramref name="bytesID"/>
/// </summary>
/// <param name="bytesID">
- /// the id to look up </param>
- /// <returns> the bytesStart offset into the internally used
- /// <seealso cref="ByteBlockPool"/> for the given id </returns>
+ /// The id to look up </param>
+ /// <returns> The bytesStart offset into the internally used
+ /// <see cref="ByteBlockPool"/> for the given id </returns>
public int ByteStart(int bytesID)
{
Debug.Assert(bytesStart != null, "bytesStart is null - not initialized");
@@ -554,8 +555,8 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Thrown if a <seealso cref="BytesRef"/> exceeds the <seealso cref="BytesRefHash"/> limit of
- /// <seealso cref="ByteBlockPool#BYTE_BLOCK_SIZE"/>-2.
+ /// Thrown if a <see cref="BytesRef"/> exceeds the <see cref="BytesRefHash"/> limit of
+ /// <see cref="ByteBlockPool.BYTE_BLOCK_SIZE"/>-2.
/// </summary>
// LUCENENET: All exeption classes should be marked serializable
#if FEATURE_SERIALIZABLE
@@ -586,37 +587,37 @@ namespace Lucene.Net.Util
public abstract class BytesStartArray
{
/// <summary>
- /// Initializes the BytesStartArray. this call will allocate memory
+ /// Initializes the <see cref="BytesStartArray"/>. This call will allocate memory.
/// </summary>
- /// <returns> the initialized bytes start array </returns>
+ /// <returns> The initialized bytes start array. </returns>
public abstract int[] Init();
/// <summary>
- /// Grows the <seealso cref="BytesStartArray"/>
+ /// Grows the <see cref="BytesStartArray"/>.
/// </summary>
- /// <returns> the grown array </returns>
+ /// <returns> The grown array. </returns>
public abstract int[] Grow();
/// <summary>
- /// clears the <seealso cref="BytesStartArray"/> and returns the cleared instance.
+ /// Clears the <see cref="BytesStartArray"/> and returns the cleared instance.
/// </summary>
- /// <returns> the cleared instance, this might be <code>null</code> </returns>
+ /// <returns> The cleared instance, this might be <c>null</c>. </returns>
public abstract int[] Clear();
/// <summary>
- /// A <seealso cref="Counter"/> reference holding the number of bytes used by this
- /// <seealso cref="BytesStartArray"/>. The <seealso cref="BytesRefHash"/> uses this reference to
- /// track it memory usage
+ /// A <see cref="Counter"/> reference holding the number of bytes used by this
+ /// <see cref="BytesStartArray"/>. The <see cref="BytesRefHash"/> uses this reference to
+ /// track it memory usage.
/// </summary>
- /// <returns> a <seealso cref="AtomicInt64"/> reference holding the number of bytes used
- /// by this <seealso cref="BytesStartArray"/>. </returns>
+ /// <returns> a <see cref="AtomicInt64"/> reference holding the number of bytes used
+ /// by this <see cref="BytesStartArray"/>. </returns>
public abstract Counter BytesUsed();
}
/// <summary>
- /// A simple <seealso cref="BytesStartArray"/> that tracks
- /// memory allocation using a private <seealso cref="Counter"/>
- /// instance.
+ /// A simple <see cref="BytesStartArray"/> that tracks
+ /// memory allocation using a private <see cref="Counter"/>
+ /// instance.
/// </summary>
public class DirectBytesStartArray : BytesStartArray
{
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/BytesRefIterator.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/BytesRefIterator.cs b/src/Lucene.Net/Util/BytesRefIterator.cs
index 5671d8d..3d2e2bc 100644
--- a/src/Lucene.Net/Util/BytesRefIterator.cs
+++ b/src/Lucene.Net/Util/BytesRefIterator.cs
@@ -20,27 +20,27 @@ namespace Lucene.Net.Util
*/
/// <summary>
- /// A simple iterator interface for <seealso cref="BytesRef"/> iteration.
+ /// A simple iterator interface for <see cref="BytesRef"/> iteration.
/// </summary>
public interface IBytesRefIterator
{
/// <summary>
- /// Increments the iteration to the next <seealso cref="BytesRef"/> in the iterator.
- /// Returns the resulting <seealso cref="BytesRef"/> or <code>null</code> if the end of
- /// the iterator is reached. The returned BytesRef may be re-used across calls
- /// to next. After this method returns null, do not call it again: the results
+ /// Increments the iteration to the next <see cref="BytesRef"/> in the iterator.
+ /// Returns the resulting <see cref="BytesRef"/> or <c>null</c> if the end of
+ /// the iterator is reached. The returned <see cref="BytesRef"/> may be re-used across calls
+ /// to <see cref="Next()"/>. After this method returns <c>null</c>, do not call it again: the results
/// are undefined.
/// </summary>
- /// <returns> the next <seealso cref="BytesRef"/> in the iterator or <code>null</code> if
+ /// <returns> The next <see cref="BytesRef"/> in the iterator or <c>null</c> if
/// the end of the iterator is reached. </returns>
- /// <exception cref="IOException"> If there is a low-level I/O error. </exception>
+ /// <exception cref="System.IO.IOException"> If there is a low-level I/O error. </exception>
BytesRef Next();
/// <summary>
- /// Return the <seealso cref="BytesRef"/> Comparer used to sort terms provided by the
- /// iterator. this may return null if there are no items or the iterator is not
+ /// Return the <see cref="BytesRef"/> Comparer used to sort terms provided by the
+ /// iterator. This may return <c>null</c> if there are no items or the iterator is not
/// sorted. Callers may invoke this method many times, so it's best to cache a
- /// single instance & reuse it.
+ /// single instance & reuse it.
/// </summary>
IComparer<BytesRef> Comparer { get; }
}
@@ -56,6 +56,9 @@ namespace Lucene.Net.Util
{
private BytesRefIterator() { } // Disallow creation
+ /// <summary>
+ /// Singleton <see cref="BytesRefIterator"/> that iterates over 0 BytesRefs.
+ /// </summary>
public static readonly IBytesRefIterator EMPTY = new EmptyBytesRefIterator();
private class EmptyBytesRefIterator : IBytesRefIterator
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/CharsRef.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/CharsRef.cs b/src/Lucene.Net/Util/CharsRef.cs
index 8779afa..432d53f 100644
--- a/src/Lucene.Net/Util/CharsRef.cs
+++ b/src/Lucene.Net/Util/CharsRef.cs
@@ -24,9 +24,10 @@ namespace Lucene.Net.Util
*/
/// <summary>
- /// Represents char[], as a slice (offset + Length) into an existing char[].
- /// The <seealso cref="#chars"/> member should never be null; use
- /// <seealso cref="#EMPTY_CHARS"/> if necessary.
+ /// Represents <see cref="T:char[]"/>, as a slice (offset + Length) into an existing <see cref="T:char[]"/>.
+ /// The <see cref="Chars"/> property should never be <c>null</c>; use
+ /// <see cref="EMPTY_CHARS"/> if necessary.
+ /// <para/>
/// @lucene.internal
/// </summary>
#if FEATURE_SERIALIZABLE
@@ -39,7 +40,7 @@ namespace Lucene.Net.Util
public static readonly char[] EMPTY_CHARS = new char[0];
/// <summary>
- /// The contents of the CharsRef. Should never be {@code null}.
+ /// The contents of the <see cref="CharsRef"/>. Should never be <c>null</c>.
/// </summary>
[WritableArray]
[SuppressMessage("Microsoft.Performance", "CA1819", Justification = "Lucene's design requires some writable array properties")]
@@ -66,7 +67,7 @@ namespace Lucene.Net.Util
public int Length { get; set; }
/// <summary>
- /// Creates a new <seealso cref="CharsRef"/> initialized an empty array zero-Length
+ /// Creates a new <see cref="CharsRef"/> initialized an empty array zero-Length
/// </summary>
public CharsRef()
: this(EMPTY_CHARS, 0, 0)
@@ -74,8 +75,8 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Creates a new <seealso cref="CharsRef"/> initialized with an array of the given
- /// capacity
+ /// Creates a new <see cref="CharsRef"/> initialized with an array of the given
+ /// <paramref name="capacity"/>.
/// </summary>
public CharsRef(int capacity)
{
@@ -83,8 +84,8 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Creates a new <seealso cref="CharsRef"/> initialized with the given array, offset and
- /// Length
+ /// Creates a new <see cref="CharsRef"/> initialized with the given <paramref name="chars"/>,
+ /// <paramref name="offset"/> and <paramref name="length"/>.
/// </summary>
public CharsRef(char[] chars, int offset, int length)
{
@@ -95,8 +96,8 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Creates a new <seealso cref="CharsRef"/> initialized with the given Strings character
- /// array
+ /// Creates a new <see cref="CharsRef"/> initialized with the given <see cref="string"/> character
+ /// array.
/// </summary>
public CharsRef(string @string)
{
@@ -110,7 +111,7 @@ 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(CharsRef)"/>
public object Clone()
{
return new CharsRef(chars, Offset, Length);
@@ -165,7 +166,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Signed int order comparison </summary>
+ /// Signed <see cref="int"/> order comparison </summary>
public int CompareTo(CharsRef other)
{
if (this == other)
@@ -199,10 +200,10 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Copies the given <seealso cref="CharsRef"/> referenced content into this instance.
+ /// Copies the given <see cref="CharsRef"/> referenced content into this instance.
/// </summary>
/// <param name="other">
- /// the <seealso cref="CharsRef"/> to copy </param>
+ /// The <see cref="CharsRef"/> to copy. </param>
public void CopyChars(CharsRef other)
{
CopyChars(other.chars, other.Offset, other.Length);
@@ -210,8 +211,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)
@@ -224,7 +226,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Copies the given array into this CharsRef.
+ /// Copies the given array into this <see cref="CharsRef"/>.
/// </summary>
public void CopyChars(char[] otherChars, int otherOffset, int otherLength)
{
@@ -238,7 +240,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Appends the given array to this CharsRef
+ /// Appends the given array to this <see cref="CharsRef"/>.
/// </summary>
public void Append(char[] otherChars, int otherOffset, int otherLength)
{
@@ -373,10 +375,10 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Creates a new CharsRef that points to a copy of the chars from
- /// <code>other</code>
- /// <p>
- /// The returned CharsRef will have a Length of other.Length
+ /// Creates a new <see cref="CharsRef"/> that points to a copy of the chars from
+ /// <paramref name="other"/>.
+ /// <para/>
+ /// The returned <see cref="CharsRef"/> will have a Length of <c>other.Length</c>
/// and an offset of zero.
/// </summary>
public static CharsRef DeepCopyOf(CharsRef other)
@@ -388,7 +390,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()
{
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/CloseableThreadLocal.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/CloseableThreadLocal.cs b/src/Lucene.Net/Util/CloseableThreadLocal.cs
index 239316c..0328a4a 100644
--- a/src/Lucene.Net/Util/CloseableThreadLocal.cs
+++ b/src/Lucene.Net/Util/CloseableThreadLocal.cs
@@ -24,31 +24,28 @@ namespace Lucene.Net.Util
/// <summary>
/// Java's builtin ThreadLocal has a serious flaw:
- /// it can take an arbitrarily long amount of time to
- /// dereference the things you had stored in it, even once the
- /// ThreadLocal instance itself is no longer referenced.
- /// this is because there is single, master map stored for
- /// each thread, which all ThreadLocals share, and that
- /// master map only periodically purges "stale" entries.
- ///
- /// While not technically a memory leak, because eventually
- /// the memory will be reclaimed, it can take a long time
- /// and you can easily hit OutOfMemoryError because from the
- /// GC's standpoint the stale entries are not reclaimable.
- ///
- /// this class works around that, by only enrolling
- /// WeakReference values into the ThreadLocal, and
- /// separately holding a hard reference to each stored
- /// value. When you call <seealso cref="#close"/>, these hard
- /// references are cleared and then GC is freely able to
- /// reclaim space by objects stored in it.
- ///
- /// We can not rely on <seealso cref="ThreadLocal#remove()"/> as it
- /// only removes the value for the caller thread, whereas
- /// <seealso cref="#close"/> takes care of all
- /// threads. You should not call <seealso cref="#close"/> until all
- /// threads are done using the instance.
- ///
+ /// it can take an arbitrarily long amount of time to
+ /// dereference the things you had stored in it, even once the
+ /// ThreadLocal instance itself is no longer referenced.
+ /// This is because there is single, master map stored for
+ /// each thread, which all ThreadLocals share, and that
+ /// master map only periodically purges "stale" entries.
+ /// <para/>
+ /// While not technically a memory leak, because eventually
+ /// the memory will be reclaimed, it can take a long time
+ /// and you can easily hit <see cref="OutOfMemoryException"/> because from the
+ /// GC's standpoint the stale entries are not reclaimable.
+ /// <para/>
+ /// This class works around that, by only enrolling
+ /// WeakReference values into the ThreadLocal, and
+ /// separately holding a hard reference to each stored
+ /// value. When you call <see cref="Dispose()"/>, these hard
+ /// references are cleared and then GC is freely able to
+ /// reclaim space by objects stored in it.
+ /// <para/>
+ /// You should not call <see cref="Dispose()"/> until all
+ /// threads are done using the instance.
+ /// <para/>
/// @lucene.internal
/// </summary>
public class DisposableThreadLocal<T> : IDisposable
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/CollectionUtil.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/CollectionUtil.cs b/src/Lucene.Net/Util/CollectionUtil.cs
index fd030d5..6b0f90f 100644
--- a/src/Lucene.Net/Util/CollectionUtil.cs
+++ b/src/Lucene.Net/Util/CollectionUtil.cs
@@ -26,7 +26,7 @@ namespace Lucene.Net.Util
/// Sort methods work directly on the supplied lists and don't copy to/from arrays
/// before/after. For medium size collections as used in the Lucene indexer that is
/// much more efficient.
- ///
+ /// <para/>
/// @lucene.internal
/// </summary>
public sealed class CollectionUtil
@@ -140,7 +140,7 @@ namespace Lucene.Net.Util
/// This method uses the intro sort
/// algorithm, but falls back to insertion sort for small lists.
/// </summary>
- /// <param name="list">this <see cref="IList{T}"/></param>
+ /// <param name="list">This <see cref="IList{T}"/></param>
/// <param name="comp">The <see cref="IComparer{T}"/> to use for the sort.</param>
public static void IntroSort<T>(IList<T> list, IComparer<T> comp)
{
@@ -157,7 +157,7 @@ namespace Lucene.Net.Util
/// This method uses the intro sort
/// algorithm, but falls back to insertion sort for small lists.
/// </summary>
- /// <param name="list">this <see cref="IList{T}"/></param>
+ /// <param name="list">This <see cref="IList{T}"/></param>
public static void IntroSort<T>(IList<T> list)
//where T : IComparable<T> // LUCENENET specific: removing constraint because in .NET, it is not needed
{
@@ -193,7 +193,7 @@ namespace Lucene.Net.Util
/// Sorts the given <see cref="IList{T}"/> in natural order.
/// This method uses the Tim sort
/// algorithm, but falls back to binary sort for small lists. </summary>
- /// <param name="list">this <see cref="IList{T}"/></param>
+ /// <param name="list">This <see cref="IList{T}"/></param>
public static void TimSort<T>(IList<T> list)
//where T : IComparable<T> // LUCENENET specific: removing constraint because in .NET, it is not needed
{
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/CommandLineUtil.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/CommandLineUtil.cs b/src/Lucene.Net/Util/CommandLineUtil.cs
index 49a000a..2d04e65 100644
--- a/src/Lucene.Net/Util/CommandLineUtil.cs
+++ b/src/Lucene.Net/Util/CommandLineUtil.cs
@@ -25,7 +25,6 @@ namespace Lucene.Net.Util
/// <summary>
/// Class containing some useful methods used by command line tools
- ///
/// </summary>
public sealed class CommandLineUtil
{
@@ -34,10 +33,10 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Creates a specific FSDirectory instance starting from its class name </summary>
- /// <param name="clazzName"> The name of the FSDirectory class to load </param>
- /// <param name="file"> The file to be used as parameter constructor </param>
- /// <returns> the new FSDirectory instance </returns>
+ /// Creates a specific <see cref="FSDirectory"/> instance starting from its class name. </summary>
+ /// <param name="clazzName"> The name of the <see cref="FSDirectory"/> class to load. </param>
+ /// <param name="dir"> The <see cref="DirectoryInfo"/> to be used as parameter constructor. </param>
+ /// <returns> The new <see cref="FSDirectory"/> instance </returns>
public static FSDirectory NewFSDirectory(string clazzName, DirectoryInfo dir)
{
try
@@ -64,20 +63,20 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Loads a specific Directory implementation </summary>
- /// <param name="clazzName"> The name of the Directory class to load </param>
- /// <returns> The Directory class loaded </returns>
- /// <exception cref="ClassNotFoundException"> If the specified class cannot be found. </exception>
+ /// Loads a specific <see cref="Directory"/> implementation. </summary>
+ /// <param name="clazzName"> The name of the <see cref="Directory"/> class to load. </param>
+ /// <returns> The <see cref="Directory"/> class loaded. </returns>
+ /// <exception cref="System.TypeLoadException"> If the specified class cannot be found. </exception>
public static Type LoadDirectoryClass(string clazzName)
{
return Type.GetType(AdjustDirectoryClassName(clazzName));
}
/// <summary>
- /// Loads a specific FSDirectory implementation </summary>
- /// <param name="clazzName"> The name of the FSDirectory class to load </param>
- /// <returns> The FSDirectory class loaded </returns>
- /// <exception cref="ClassNotFoundException"> If the specified class cannot be found. </exception>
+ /// Loads a specific <see cref="FSDirectory"/> implementation. </summary>
+ /// <param name="clazzName"> The name of the <see cref="FSDirectory"/> class to load. </param>
+ /// <returns> The <see cref="FSDirectory"/> class loaded. </returns>
+ /// <exception cref="System.TypeLoadException"> If the specified class cannot be found. </exception>
public static Type LoadFSDirectoryClass(string clazzName)
{
return Type.GetType(AdjustDirectoryClassName(clazzName));
@@ -98,14 +97,14 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Creates a new specific FSDirectory instance </summary>
+ /// Creates a new specific <see cref="FSDirectory"/> instance. </summary>
/// <param name="clazz"> The class of the object to be created </param>
- /// <param name="file"> The file to be used as parameter constructor </param>
- /// <returns> The new FSDirectory instance </returns>
- /// <exception cref="NoSuchMethodException"> If the Directory does not have a constructor that takes <code>File</code>. </exception>
- /// <exception cref="InstantiationException"> If the class is abstract or an interface. </exception>
- /// <exception cref="IllegalAccessException"> If the constructor does not have public visibility. </exception>
- /// <exception cref="InvocationTargetException"> If the constructor throws an exception </exception>
+ /// <param name="dir"> The <see cref="DirectoryInfo"/> to be used as parameter constructor </param>
+ /// <returns> The new <see cref="FSDirectory"/> instance. </returns>
+ /// <exception cref="MissingMethodException"> If the <see cref="Directory"/> does not have a constructor that takes <see cref="DirectoryInfo"/>. </exception>
+ /// <exception cref="MemberAccessException"> If the class is abstract or an interface. </exception>
+ /// <exception cref="TypeLoadException"> If the constructor does not have public visibility. </exception>
+ /// <exception cref="System.Reflection.TargetInvocationException"> If the constructor throws an exception </exception>
public static FSDirectory NewFSDirectory(Type clazz, DirectoryInfo dir)
{
// Assuming every FSDirectory has a ctor(File):
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/Constants.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/Constants.cs b/src/Lucene.Net/Util/Constants.cs
index 1086467..5dfd556 100644
--- a/src/Lucene.Net/Util/Constants.cs
+++ b/src/Lucene.Net/Util/Constants.cs
@@ -39,15 +39,19 @@ namespace Lucene.Net.Util
// LUCENENET NOTE: IMPORTANT - this line must be placed before RUNTIME_VERSION so it can be parsed.
private static Regex VERSION_PARSER = new Regex(@"(\d+\.\d+\.\d+\.\d+)", RegexOptions.Compiled);
- /// <summary>
#if NETSTANDARD
+ /// <summary>
/// The value of the version parsed from <see cref="RuntimeInformation.FrameworkDescription"/>.
+ /// <para/>
+ /// NOTE: This was JAVA_VERSION in Lucene
+ /// </summary>
#else
+ /// <summary>
/// The value of <see cref="Environment.Version"/>.
-#endif
/// <para/>
/// NOTE: This was JAVA_VERSION in Lucene
/// </summary>
+#endif
public static readonly string RUNTIME_VERSION = GetEnvironmentVariable("RUNTIME_VERSION", "?");
@@ -173,10 +177,10 @@ namespace Lucene.Net.Util
// We should never change index format with minor versions, so it should always be x.y or x.y.0.z for alpha/beta versions!
/// <summary>
/// this is the internal Lucene version, recorded into each segment.
- /// NOTE: we track per-segment version as a String with the {@code "X.Y"} format
- /// (no minor version), e.g. {@code "4.0", "3.1", "3.0"}.
- /// <p>Alpha and Beta versions will have numbers like {@code "X.Y.0.Z"},
- /// anything else is not allowed. this is done to prevent people from
+ /// NOTE: we track per-segment version as a <see cref="string"/> with the <c>"X.Y"</c> format
+ /// (no minor version), e.g. <c>"4.0", "3.1", "3.0"</c>.
+ /// <para/>Alpha and Beta versions will have numbers like <c>"X.Y.0.Z"</c>,
+ /// anything else is not allowed. This is done to prevent people from
/// using indexes created with ALPHA/BETA versions with the released version.
/// </summary>
public static readonly string LUCENE_MAIN_VERSION = Ident("4.8");
@@ -186,7 +190,7 @@ namespace Lucene.Net.Util
// it might make sense to change it when a major/minor/patch
// port to Lucene is done).
/// <summary>
- /// this is the Lucene version for display purposes.
+ /// This is the Lucene version for display purposes.
/// </summary>
public static readonly string LUCENE_VERSION = "4.8.0";
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/Counter.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/Counter.cs b/src/Lucene.Net/Util/Counter.cs
index 099b8ee..93991f5 100644
--- a/src/Lucene.Net/Util/Counter.cs
+++ b/src/Lucene.Net/Util/Counter.cs
@@ -21,24 +21,24 @@ namespace Lucene.Net.Util
/// <summary>
/// Simple counter class
- ///
+ /// <para/>
/// @lucene.internal
/// @lucene.experimental
/// </summary>
public abstract class Counter
{
/// <summary>
- /// Adds the given delta to the counters current value
+ /// Adds the given delta to the counters current value.
/// </summary>
/// <param name="delta">
- /// the delta to add </param>
- /// <returns> the counters updated value </returns>
+ /// The delta to add. </param>
+ /// <returns> The counters updated value. </returns>
public abstract long AddAndGet(long delta);
/// <summary>
- /// Returns the counters current value
+ /// Returns the counters current value.
/// </summary>
- /// <returns> the counters current value </returns>
+ /// <returns> The counters current value. </returns>
public abstract long Get();
/// <summary>
@@ -53,9 +53,9 @@ namespace Lucene.Net.Util
/// Returns a new counter.
/// </summary>
/// <param name="threadSafe">
- /// <code>true</code> if the returned counter can be used by multiple
+ /// <c>true</c> if the returned counter can be used by multiple
/// threads concurrently. </param>
- /// <returns> a new counter. </returns>
+ /// <returns> A new counter. </returns>
public static Counter NewCounter(bool threadSafe)
{
return threadSafe ? (Counter)new AtomicCounter() : new SerialCounter();
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/DocIdBitSet.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/DocIdBitSet.cs b/src/Lucene.Net/Util/DocIdBitSet.cs
index db1c04f..7531446 100644
--- a/src/Lucene.Net/Util/DocIdBitSet.cs
+++ b/src/Lucene.Net/Util/DocIdBitSet.cs
@@ -25,7 +25,7 @@ namespace Lucene.Net.Util
using DocIdSetIterator = Lucene.Net.Search.DocIdSetIterator;
/// <summary>
- /// Simple DocIdSet and DocIdSetIterator backed by a BitSet
+ /// Simple <see cref="DocIdSet"/> and <see cref="DocIdSetIterator"/> backed by a <see cref="BitArray"/>
/// </summary>
#if FEATURE_SERIALIZABLE
[Serializable]
@@ -50,7 +50,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// this DocIdSet implementation is cacheable. </summary>
+ /// This DocIdSet implementation is cacheable. </summary>
public override bool IsCacheable
{
get
@@ -60,7 +60,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Returns the underlying BitSet.
+ /// Returns the underlying <see cref="BitArray"/>.
/// </summary>
public virtual BitArray BitSet
{
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/DoubleBarrelLRUCache.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/DoubleBarrelLRUCache.cs b/src/Lucene.Net/Util/DoubleBarrelLRUCache.cs
index 0bd5d2e..316fd9e 100644
--- a/src/Lucene.Net/Util/DoubleBarrelLRUCache.cs
+++ b/src/Lucene.Net/Util/DoubleBarrelLRUCache.cs
@@ -25,19 +25,19 @@ namespace Lucene.Net.Util
/// Simple concurrent LRU cache, using a "double barrel"
/// approach where two ConcurrentHashMaps record entries.
///
- /// <p>At any given time, one hash is primary and the other
- /// is secondary. <seealso cref="#get"/> first checks primary, and if
+ /// <para>At any given time, one hash is primary and the other
+ /// is secondary. <see cref="Get(TKey)"/> first checks primary, and if
/// that's a miss, checks secondary. If secondary has the
/// entry, it's promoted to primary (<b>NOTE</b>: the key is
/// cloned at this point). Once primary is full, the
- /// secondary is cleared and the two are swapped.</p>
+ /// secondary is cleared and the two are swapped.</para>
///
- /// <p>this is not as space efficient as other possible
+ /// <para>This is not as space efficient as other possible
/// concurrent approaches (see LUCENE-2075): to achieve
/// perfect LRU(N) it requires 2*N storage. But, this
/// approach is relatively simple and seems in practice to
/// not grow unbounded in size when under hideously high
- /// load.</p>
+ /// load.</para>
///
/// @lucene.internal
/// </summary>
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/FieldCacheSanityChecker.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/FieldCacheSanityChecker.cs b/src/Lucene.Net/Util/FieldCacheSanityChecker.cs
index f42d53a..ca6d281 100644
--- a/src/Lucene.Net/Util/FieldCacheSanityChecker.cs
+++ b/src/Lucene.Net/Util/FieldCacheSanityChecker.cs
@@ -28,10 +28,11 @@ namespace Lucene.Net.Util
using IndexReader = Lucene.Net.Index.IndexReader;
/// <summary>
+ /// <para>
/// Provides methods for sanity checking that entries in the FieldCache
/// are not wasteful or inconsistent.
- /// </p>
- /// <p>
+ /// </para>
+ /// <para>
/// Lucene 2.9 Introduced numerous enhancements into how the FieldCache
/// is used by the low levels of Lucene searching (for Sorting and
/// ValueSourceQueries) to improve both the speed for Sorting, as well
@@ -40,14 +41,15 @@ namespace Lucene.Net.Util
/// MultiReader or DirectoryReader) down to the leaf level SegmentReaders.
/// As a result, existing applications that directly access the FieldCache
/// may find RAM usage increase significantly when upgrading to 2.9 or
- /// Later. this class provides an API for these applications (or their
+ /// Later. This class provides an API for these applications (or their
/// Unit tests) to check at run time if the FieldCache contains "insane"
/// usages of the FieldCache.
- /// </p>
- /// @lucene.experimental </summary>
- /// <seealso cref= FieldCache </seealso>
- /// <seealso cref= FieldCacheSanityChecker.Insanity </seealso>
- /// <seealso cref= FieldCacheSanityChecker.InsanityType </seealso>
+ /// </para>
+ /// @lucene.experimental
+ /// </summary>
+ /// <seealso cref="IFieldCache"/>
+ /// <seealso cref="FieldCacheSanityChecker.Insanity"/>
+ /// <seealso cref="FieldCacheSanityChecker.InsanityType"/>
public sealed class FieldCacheSanityChecker
{
private bool estimateRam;
@@ -57,7 +59,7 @@ namespace Lucene.Net.Util
/* NOOP */
}
- /// <param name="estimateRam">If set, estimate size for all CacheEntry objects will be calculated.</param>
+ /// <param name="estimateRam">If set, estimate size for all <see cref="FieldCache.CacheEntry"/> objects will be calculated.</param>
// LUCENENET specific - added this constructor overload so we wouldn't need a (ridiculous) SetRamUsageEstimator() method
public FieldCacheSanityChecker(bool estimateRam)
{
@@ -75,7 +77,7 @@ namespace Lucene.Net.Util
/// <summary>
/// Quick and dirty convenience method </summary>
- /// <seealso cref= #check </seealso>
+ /// <seealso cref="Check(FieldCache.CacheEntry[])"/>
public static Insanity[] CheckSanity(IFieldCache cache)
{
return CheckSanity(cache.GetCacheEntries());
@@ -83,8 +85,8 @@ namespace Lucene.Net.Util
/// <summary>
/// Quick and dirty convenience method that instantiates an instance with
- /// "good defaults" and uses it to test the CacheEntrys </summary>
- /// <seealso cref= #check </seealso>
+ /// "good defaults" and uses it to test the <see cref="FieldCache.CacheEntry"/>s </summary>
+ /// <seealso cref="Check(FieldCache.CacheEntry[])"/>
public static Insanity[] CheckSanity(params FieldCache.CacheEntry[] cacheEntries)
{
FieldCacheSanityChecker sanityChecker = new FieldCacheSanityChecker(estimateRam: true);
@@ -93,10 +95,10 @@ namespace Lucene.Net.Util
/// <summary>
/// Tests a CacheEntry[] for indication of "insane" cache usage.
- /// <p>
- /// <B>NOTE:</b>FieldCache CreationPlaceholder objects are ignored.
+ /// <para>
+ /// <b>NOTE:</b>FieldCache CreationPlaceholder objects are ignored.
/// (:TODO: is this a bad idea? are we masking a real problem?)
- /// </p>
+ /// </para>
/// </summary>
public Insanity[] Check(params FieldCache.CacheEntry[] cacheEntries)
{
@@ -164,10 +166,10 @@ namespace Lucene.Net.Util
/// <summary>
/// Internal helper method used by check that iterates over
- /// valMismatchKeys and generates a Collection of Insanity
- /// instances accordingly. The MapOfSets are used to populate
- /// the Insanity objects. </summary>
- /// <seealso cref= InsanityType#VALUEMISMATCH </seealso>
+ /// <paramref name="valMismatchKeys"/> and generates a <see cref="ICollection{T}"/> of <see cref="Insanity"/>
+ /// instances accordingly. The <see cref="MapOfSets{TKey, TValue}"/> are used to populate
+ /// the <see cref="Insanity"/> objects. </summary>
+ /// <seealso cref="InsanityType.VALUEMISMATCH"/>
private ICollection<Insanity> CheckValueMismatch(MapOfSets<int, FieldCache.CacheEntry> valIdToItems, MapOfSets<ReaderField, int> readerFieldToValIds, ISet<ReaderField> valMismatchKeys)
{
List<Insanity> insanity = new List<Insanity>(valMismatchKeys.Count * 3);
@@ -200,11 +202,11 @@ namespace Lucene.Net.Util
/// <summary>
/// Internal helper method used by check that iterates over
- /// the keys of readerFieldToValIds and generates a Collection
- /// of Insanity instances whenever two (or more) ReaderField instances are
+ /// the keys of <paramref name="readerFieldToValIds"/> and generates a <see cref="ICollection{T}"/>
+ /// of <see cref="Insanity"/> instances whenever two (or more) <see cref="ReaderField"/> instances are
/// found that have an ancestry relationships.
/// </summary>
- /// <seealso cref= InsanityType#SUBREADER </seealso>
+ /// <seealso cref="InsanityType.SUBREADER"/>
private ICollection<Insanity> CheckSubreaders(MapOfSets<int, FieldCache.CacheEntry> valIdToItems, MapOfSets<ReaderField, int> readerFieldToValIds)
{
List<Insanity> insanity = new List<Insanity>(23);
@@ -281,9 +283,9 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Checks if the seed is an IndexReader, and if so will walk
+ /// Checks if the <paramref name="seed"/> is an <see cref="IndexReader"/>, and if so will walk
/// the hierarchy of subReaders building up a list of the objects
- /// returned by {@code seed.getCoreCacheKey()}
+ /// returned by <c>seed.CoreCacheKey</c>
/// </summary>
private IList<object> GetAllDescendantReaderKeys(object seed)
{
@@ -359,9 +361,9 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Simple container for a collection of related CacheEntry objects that
+ /// Simple container for a collection of related <see cref="FieldCache.CacheEntry"/> objects that
/// in conjunction with each other represent some "insane" usage of the
- /// FieldCache.
+ /// <see cref="IFieldCache"/>.
/// </summary>
public sealed class Insanity
{
@@ -396,7 +398,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Description of hte insane behavior
+ /// Description of the insane behavior
/// </summary>
public string Msg
{
@@ -407,7 +409,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// CacheEntry objects which suggest a problem
+ /// <see cref="FieldCache.CacheEntry"/> objects which suggest a problem
/// </summary>
[WritableArray]
[SuppressMessage("Microsoft.Performance", "CA1819", Justification = "Lucene's design requires some writable array properties")]
@@ -417,8 +419,8 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// Multi-Line representation of this Insanity object, starting with
- /// the Type and Msg, followed by each CacheEntry.toString() on it's
+ /// Multi-Line representation of this <see cref="Insanity"/> object, starting with
+ /// the Type and Msg, followed by each CacheEntry.ToString() on it's
/// own line prefaced by a tab character
/// </summary>
public override string ToString()
@@ -446,11 +448,11 @@ namespace Lucene.Net.Util
/// <summary>
/// An Enumeration of the different types of "insane" behavior that
- /// may be detected in a FieldCache.
+ /// may be detected in a <see cref="IFieldCache"/>.
/// </summary>
- /// <seealso cref= InsanityType#SUBREADER </seealso>
- /// <seealso cref= InsanityType#VALUEMISMATCH </seealso>
- /// <seealso cref= InsanityType#EXPECTED </seealso>
+ /// <seealso cref="InsanityType.SUBREADER"/>
+ /// <seealso cref="InsanityType.VALUEMISMATCH"/>
+ /// <seealso cref="InsanityType.EXPECTED"/>
public sealed class InsanityType
{
private readonly string label;
@@ -472,24 +474,24 @@ namespace Lucene.Net.Util
public static readonly InsanityType SUBREADER = new InsanityType("SUBREADER");
/// <summary>
- /// <p>
+ /// <para>
/// Indicates entries have the same reader+fieldname but
- /// different cached values. this can happen if different datatypes,
+ /// different cached values. This can happen if different datatypes,
/// or parsers are used -- and while it's not necessarily a bug
/// it's typically an indication of a possible problem.
- /// </p>
- /// <p>
+ /// </para>
+ /// <para>
/// <b>NOTE:</b> Only the reader, fieldname, and cached value are actually
/// tested -- if two cache entries have different parsers or datatypes but
- /// the cached values are the same Object (== not just equal()) this method
- /// does not consider that a red flag. this allows for subtle variations
+ /// the cached values are the same Object (== not just Equal()) this method
+ /// does not consider that a red flag. This allows for subtle variations
/// in the way a Parser is specified (null vs DEFAULT_INT64_PARSER, etc...)
- /// </p>
+ /// </para>
/// </summary>
public static readonly InsanityType VALUEMISMATCH = new InsanityType("VALUEMISMATCH");
/// <summary>
- /// Indicates an expected bit of "insanity". this may be useful for
+ /// Indicates an expected bit of "insanity". This may be useful for
/// clients that wish to preserve/log information about insane usage
/// but indicate that it was expected.
/// </summary>
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/FilterIterator.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/FilterIterator.cs b/src/Lucene.Net/Util/FilterIterator.cs
index f4c8743..4ede14d 100644
--- a/src/Lucene.Net/Util/FilterIterator.cs
+++ b/src/Lucene.Net/Util/FilterIterator.cs
@@ -22,8 +22,8 @@ namespace Lucene.Net.Util
*/
/// <summary>
- /// An <seealso cref="Iterator"/> implementation that filters elements with a boolean predicate. </summary>
- /// <seealso cref= #predicateFunction </seealso>
+ /// An <see cref="IEnumerator{T}"/> implementation that filters elements with a boolean predicate. </summary>
+ /// <seealso cref="PredicateFunction(T)"/>
public abstract class FilterIterator<T> : IEnumerator<T>
{
private readonly IEnumerator<T> iter;
@@ -32,7 +32,7 @@ namespace Lucene.Net.Util
private T current = default(T);
/// <summary>
- /// returns true, if this element should be returned by <seealso cref="#next()"/>. </summary>
+ /// Returns <c>true</c>, if this element should be set to <see cref="Current"/> by <see cref="SetNext()"/>. </summary>
protected abstract bool PredicateFunction(T @object);
public FilterIterator(IEnumerator<T> baseIterator)
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/FixedBitSet.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/FixedBitSet.cs b/src/Lucene.Net/Util/FixedBitSet.cs
index 0f4aa34..ff9b91d 100644
--- a/src/Lucene.Net/Util/FixedBitSet.cs
+++ b/src/Lucene.Net/Util/FixedBitSet.cs
@@ -25,18 +25,18 @@ namespace Lucene.Net.Util
using DocIdSetIterator = Lucene.Net.Search.DocIdSetIterator;
/// <summary>
- /// BitSet of fixed length (numBits), backed by accessible (<seealso cref="#getBits"/>)
- /// long[], accessed with an int index, implementing <seealso cref="GetBits"/> and
- /// <seealso cref="DocIdSet"/>. If you need to manage more than 2.1B bits, use
- /// <seealso cref="Int64BitSet"/>.
- ///
+ /// BitSet of fixed length (numBits), backed by accessible (<see cref="GetBits()"/>)
+ /// long[], accessed with an int index, implementing <see cref="GetBits()"/> and
+ /// <see cref="DocIdSet"/>. If you need to manage more than 2.1B bits, use
+ /// <see cref="Int64BitSet"/>.
+ /// <para/>
/// @lucene.internal
/// </summary>
public sealed class FixedBitSet : DocIdSet, IBits
{
/// <summary>
- /// A <seealso cref="DocIdSetIterator"/> which iterates over set bits in a
- /// <seealso cref="FixedBitSet"/>.
+ /// A <see cref="DocIdSetIterator"/> which iterates over set bits in a
+ /// <see cref="FixedBitSet"/>.
/// </summary>
public sealed class FixedBitSetIterator : DocIdSetIterator
{
@@ -45,7 +45,7 @@ namespace Lucene.Net.Util
internal int doc = -1;
/// <summary>
- /// Creates an iterator over the given <seealso cref="FixedBitSet"/>. </summary>
+ /// Creates an iterator over the given <see cref="FixedBitSet"/>. </summary>
public FixedBitSetIterator(FixedBitSet bits)
: this(bits.bits, bits.numBits, bits.numWords)
{
@@ -126,14 +126,14 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// If the given <seealso cref="FixedBitSet"/> is large enough to hold {@code numBits},
- /// returns the given bits, otherwise returns a new <seealso cref="FixedBitSet"/> which
+ /// If the given <see cref="FixedBitSet"/> is large enough to hold <paramref name="numBits"/>,
+ /// returns the given bits, otherwise returns a new <see cref="FixedBitSet"/> which
/// can hold the requested number of bits.
///
- /// <p>
- /// <b>NOTE:</b> the returned bitset reuses the underlying {@code long[]} of
- /// the given {@code bits} if possible. Also, calling <seealso cref="#length()"/> on the
- /// returned bits may return a value greater than {@code numBits}.
+ /// <para/>
+ /// <b>NOTE:</b> the returned bitset reuses the underlying <see cref="T:long[]"/> of
+ /// the given <paramref name="bits"/> if possible. Also, calling <see cref="Length"/> on the
+ /// returned bits may return a value greater than <paramref name="numBits"/>.
/// </summary>
public static FixedBitSet EnsureCapacity(FixedBitSet bits, int numBits)
{
@@ -154,7 +154,7 @@ 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(int numBits)
{
int numLong = (int)((uint)numBits >> 6);
@@ -244,7 +244,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// this DocIdSet implementation is cacheable. </summary>
+ /// This DocIdSet implementation is cacheable. </summary>
public override bool IsCacheable
{
get
@@ -263,8 +263,8 @@ namespace Lucene.Net.Util
/// <summary>
/// Returns number of set bits. NOTE: this visits every
- /// long in the backing bits array, and the result is not
- /// internally cached!
+ /// <see cref="long"/> in the backing bits array, and the result is not
+ /// internally cached!
/// </summary>
public int Cardinality()
{
@@ -324,7 +324,7 @@ 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.
+ /// -1 is returned if there are no more set bits.
/// </summary>
public int NextSetBit(int index)
{
@@ -352,7 +352,7 @@ namespace Lucene.Net.Util
/// <summary>
/// Returns the index of the last set bit before or on the index specified.
- /// -1 is returned if there are no more set bits.
+ /// -1 is returned if there are no more set bits.
/// </summary>
public int PrevSetBit(int index)
{
@@ -380,7 +380,7 @@ namespace Lucene.Net.Util
/// <summary>
/// Does in-place OR of the bits provided by the
- /// iterator.
+ /// iterator.
/// </summary>
public void Or(DocIdSetIterator iter)
{
@@ -455,7 +455,7 @@ namespace Lucene.Net.Util
/// <summary>
/// Does in-place AND of the bits provided by the
- /// iterator.
+ /// iterator.
/// </summary>
public void And(DocIdSetIterator iter)
{
@@ -496,7 +496,7 @@ namespace Lucene.Net.Util
}
/// <summary>
- /// returns true if the sets have any elements in common </summary>
+ /// Returns true if the sets have any elements in common </summary>
public bool Intersects(FixedBitSet other)
{
int pos = Math.Min(numWords, other.numWords);
@@ -533,7 +533,7 @@ namespace Lucene.Net.Util
/// <summary>
/// Does in-place AND NOT of the bits provided by the
- /// iterator.
+ /// iterator.
/// </summary>
public void AndNot(DocIdSetIterator iter)
{
@@ -587,8 +587,8 @@ namespace Lucene.Net.Util
/// <summary>
/// Flips a range of bits
/// </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 void Flip(int startIndex, int endIndex)
{
Debug.Assert(startIndex >= 0 && startIndex < numBits);
@@ -633,8 +633,8 @@ namespace Lucene.Net.Util
/// <summary>
/// Sets a range of bits
/// </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 void Set(int startIndex, int endIndex)
{
Debug.Assert(startIndex >= 0 && startIndex < numBits);
@@ -665,8 +665,8 @@ namespace Lucene.Net.Util
/// <summary>
/// Clears a range of bits.
/// </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 void Clear(int startIndex, int endIndex)
{
Debug.Assert(startIndex >= 0 && startIndex < numBits, "startIndex=" + startIndex + ", numBits=" + numBits);
@@ -707,7 +707,7 @@ namespace Lucene.Net.Util
}
/// <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/d7cb70c4/src/Lucene.Net/Util/GrowableByteArrayDataOutput.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/GrowableByteArrayDataOutput.cs b/src/Lucene.Net/Util/GrowableByteArrayDataOutput.cs
index 208a14c..49c6b66 100644
--- a/src/Lucene.Net/Util/GrowableByteArrayDataOutput.cs
+++ b/src/Lucene.Net/Util/GrowableByteArrayDataOutput.cs
@@ -23,7 +23,8 @@ namespace Lucene.Net.Util
using DataOutput = Lucene.Net.Store.DataOutput;
/// <summary>
- /// A <seealso cref="DataOutput"/> that can be used to build a byte[].
+ /// A <see cref="DataOutput"/> that can be used to build a <see cref="T:byte[]"/>.
+ /// <para/>
/// @lucene.internal
/// </summary>
public sealed class GrowableByteArrayDataOutput : DataOutput
@@ -44,7 +45,7 @@ namespace Lucene.Net.Util
public int Length { get; set; }
/// <summary>
- /// Create a <seealso cref="GrowableByteArrayDataOutput"/> with the given initial capacity. </summary>
+ /// Create a <see cref="GrowableByteArrayDataOutput"/> with the given initial capacity. </summary>
public GrowableByteArrayDataOutput(int cp)
{
this.bytes = new byte[ArrayUtil.Oversize(cp, 1)];
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/d7cb70c4/src/Lucene.Net/Util/IAttributeReflector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net/Util/IAttributeReflector.cs b/src/Lucene.Net/Util/IAttributeReflector.cs
deleted file mode 100644
index 07019d3..0000000
--- a/src/Lucene.Net/Util/IAttributeReflector.cs
+++ /dev/null
@@ -1,29 +0,0 @@
-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.
- */
-
- public interface IAttributeReflector
- {
- void Reflect<T>(string key, object value)
- where T : IAttribute;
-
- void Reflect(Type type, string key, object value);
- }
-}
\ No newline at end of file