http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/PriorityQueue.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/PriorityQueue.cs b/src/Lucene.Net/Util/PriorityQueue.cs index a2f4e07..36d5be5 100644 --- a/src/Lucene.Net/Util/PriorityQueue.cs +++ b/src/Lucene.Net/Util/PriorityQueue.cs @@ -23,16 +23,16 @@ namespace Lucene.Net.Util */ /// <summary> - /// A PriorityQueue maintains a partial ordering of its elements such that the - /// element with least priority can always be found in constant time. It is represented as a - /// Min-Heap so that Add()'s and Pop()'s require log(size) time. + /// A <see cref="PriorityQueue{T}"/> maintains a partial ordering of its elements such that the + /// element with least priority can always be found in constant time. Put()'s and Pop()'s + /// require log(size) time. /// - /// <p><b>NOTE</b>: this class will pre-allocate a full array of - /// length <code>maxSize+1</code> if instantiated via the - /// <seealso cref="#PriorityQueue(int,boolean)"/> constructor with - /// <code>prepopulate</code> set to <code>true</code>. That maximum + /// <para/><b>NOTE</b>: this class will pre-allocate a full array of + /// length <c>maxSize+1</c> if instantiated via the + /// <see cref="PriorityQueue(int, bool)"/> constructor with + /// <c>prepopulate</c> set to <c>true</c>. That maximum /// size can grow as we insert elements over the time. - /// + /// <para/> /// @lucene.internal /// </summary> #if FEATURE_SERIALIZABLE @@ -102,48 +102,48 @@ namespace Lucene.Net.Util /// <summary> /// Determines the ordering of objects in this priority queue. Subclasses - /// must define this one method. </summary> - /// <returns> <code>true</code> iff parameter <tt>a</tt> is less than parameter <tt>b</tt>. </returns> + /// must define this one method. </summary> + /// <returns> <c>true</c> if parameter <paramref name="a"/> is less than parameter <paramref name="b"/>. </returns> protected internal abstract bool LessThan(T a, T b); /// <summary> - /// this method can be overridden by extending classes to return a sentinel - /// object which will be used by the <seealso cref="PriorityQueue#PriorityQueue(int,boolean)"/> + /// This method can be overridden by extending classes to return a sentinel + /// object which will be used by the <see cref="PriorityQueue(int, bool)"/> /// constructor to fill the queue, so that the code which uses that queue can always /// assume it's full and only change the top without attempting to insert any new - /// object.<br> - /// + /// object. + /// <para/> /// Those sentinel values should always compare worse than any non-sentinel - /// value (i.e., <seealso cref="#lessThan"/> should always favor the - /// non-sentinel values).<br> - /// - /// By default, this method returns false, which means the queue will not be + /// value (i.e., <see cref="LessThan(T, T)"/> should always favor the + /// non-sentinel values). + /// <para/> + /// By default, this method returns <c>false</c>, which means the queue will not be /// filled with sentinel values. Otherwise, the value returned will be used to - /// pre-populate the queue. Adds sentinel values to the queue.<br> - /// + /// pre-populate the queue. Adds sentinel values to the queue. + /// <para/> /// If this method is extended to return a non-null value, then the following /// usage pattern is recommended: /// - /// <pre class="prettyprint"> - /// // extends getSentinelObject() to return a non-null value. + /// <code> + /// // extends GetSentinelObject() to return a non-null value. /// PriorityQueue<MyObject> pq = new MyQueue<MyObject>(numHits); /// // save the 'top' element, which is guaranteed to not be null. - /// MyObject pqTop = pq.top(); + /// MyObject pqTop = pq.Top; /// <...> /// // now in order to add a new element, which is 'better' than top (after /// // you've verified it is better), it is as simple as: - /// pqTop.change(). - /// pqTop = pq.updateTop(); - /// </pre> - /// - /// <b>NOTE:</b> if this method returns a non-null value, it will be called by - /// the <seealso cref="PriorityQueue#PriorityQueue(int,boolean)"/> constructor - /// <seealso cref="#size()"/> times, relying on a new object to be returned and will not - /// check if it's null again. Therefore you should ensure any call to this + /// pqTop.Change(). + /// pqTop = pq.UpdateTop(); + /// </code> + /// <para/> + /// <b>NOTE:</b> if this method returns a non-<c>null</c> value, it will be called by + /// the <see cref="PriorityQueue(int, bool)"/> constructor + /// <see cref="Count"/> times, relying on a new object to be returned and will not + /// check if it's <c>null</c> again. Therefore you should ensure any call to this /// method creates a new instance and behaves consistently, e.g., it cannot - /// return null if it previously returned non-null. + /// return <c>null</c> if it previously returned non-<c>null</c>. /// </summary> - /// <returns> the sentinel object to use to pre-populate the queue, or null if + /// <returns> The sentinel object to use to pre-populate the queue, or <c>null</c> if /// sentinel objects are not supported. </returns> protected virtual T GetSentinelObject() { @@ -151,11 +151,11 @@ namespace Lucene.Net.Util } /// <summary> - /// Adds an Object to a PriorityQueue in log(size) time. If one tries to add - /// more objects than maxSize from initialize and it is not possible to resize - /// the heap, an <seealso cref="IndexOutOfRangeException"/> is thrown. + /// Adds an Object to a <see cref="PriorityQueue{T}"/> in log(size) time. If one tries to add + /// more objects than <see cref="maxSize"/> from initialize and it is not possible to resize + /// the heap, an <see cref="IndexOutOfRangeException"/> is thrown. /// </summary> - /// <returns> the new 'top' element in the queue. </returns> + /// <returns> The new 'top' element in the queue. </returns> public T Add(T element) { size++; @@ -165,14 +165,14 @@ namespace Lucene.Net.Util } /// <summary> - /// Adds an Object to a PriorityQueue in log(size) time. + /// Adds an Object to a <see cref="PriorityQueue{T}"/> in log(size) time. /// It returns the object (if any) that was - /// dropped off the heap because it was full. this can be + /// dropped off the heap because it was full. This can be /// the given parameter (in case it is smaller than the /// full heap's minimum, and couldn't be added), or another /// object that was previously the smallest value in the - /// heap and now has been replaced by a larger one, or null - /// if the queue wasn't yet full with maxSize elements. + /// heap and now has been replaced by a larger one, or <c>null</c> + /// if the queue wasn't yet full with <see cref="maxSize"/> elements. /// </summary> public virtual T InsertWithOverflow(T element) { @@ -195,8 +195,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns the least element of the PriorityQueue in constant time. - /// Returns null if the queue is empty. </summary> + /// Returns the least element of the <see cref="PriorityQueue{T}"/> in constant time. + /// Returns <c>null</c> if the queue is empty. </summary> public T Top { get @@ -209,8 +209,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Removes and returns the least element of the PriorityQueue in log(size) - /// time. + /// Removes and returns the least element of the <see cref="PriorityQueue{T}"/> in log(size) + /// time. /// </summary> public T Pop() { @@ -233,20 +233,20 @@ namespace Lucene.Net.Util /// Should be called when the Object at top changes values. Still log(n) worst /// case, but it's at least twice as fast to /// - /// <pre class="prettyprint"> - /// pq.top().change(); - /// pq.updateTop(); - /// </pre> + /// <code> + /// pq.Top.Change(); + /// pq.UpdateTop(); + /// </code> /// /// instead of /// - /// <pre class="prettyprint"> - /// o = pq.pop(); - /// o.change(); - /// pq.push(o); - /// </pre> + /// <code> + /// o = pq.Pop(); + /// o.Change(); + /// pq.Push(o); + /// </code> /// </summary> - /// <returns> the new 'top' element. </returns> + /// <returns> The new 'top' element. </returns> public T UpdateTop() { DownHeap(); @@ -254,7 +254,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns the number of elements currently stored in the PriorityQueue. + /// Returns the number of elements currently stored in the <see cref="PriorityQueue{T}"/>. /// NOTE: This was size() in Lucene. /// </summary> public int Count @@ -263,7 +263,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Removes all entries from the PriorityQueue. </summary> + /// Removes all entries from the <see cref="PriorityQueue{T}"/>. </summary> public void Clear() { for (int i = 0; i <= size; i++) @@ -312,7 +312,8 @@ namespace Lucene.Net.Util } /// <summary> - /// this method returns the internal heap array as T[]. + /// This method returns the internal heap array as T[]. + /// <para/> /// @lucene.internal /// </summary> [WritableArray]
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/QueryBuilder.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/QueryBuilder.cs b/src/Lucene.Net/Util/QueryBuilder.cs index 18cd2d0..286b4e2 100644 --- a/src/Lucene.Net/Util/QueryBuilder.cs +++ b/src/Lucene.Net/Util/QueryBuilder.cs @@ -36,18 +36,18 @@ namespace Lucene.Net.Util using TokenStream = Lucene.Net.Analysis.TokenStream; /// <summary> - /// Creates queries from the <seealso cref="Analyzer"/> chain. - /// <p> + /// Creates queries from the <see cref="Analyzer"/> chain. + /// <para/> /// Example usage: - /// <pre class="prettyprint"> - /// QueryBuilder builder = new QueryBuilder(analyzer); - /// Query a = builder.createBooleanQuery("body", "just a test"); - /// Query b = builder.createPhraseQuery("body", "another test"); - /// Query c = builder.createMinShouldMatchQuery("body", "another test", 0.5f); - /// </pre> - /// <p> - /// this can also be used as a subclass for query parsers to make it easier - /// to interact with the analysis chain. Factory methods such as {@code newTermQuery} + /// <code> + /// QueryBuilder builder = new QueryBuilder(analyzer); + /// Query a = builder.CreateBooleanQuery("body", "just a test"); + /// Query b = builder.CreatePhraseQuery("body", "another test"); + /// Query c = builder.CreateMinShouldMatchQuery("body", "another test", 0.5f); + /// </code> + /// <para/> + /// This can also be used as a subclass for query parsers to make it easier + /// to interact with the analysis chain. Factory methods such as <see cref="NewTermQuery(Term)"/> /// are provided so that the generated queries can be customized. /// </summary> public class QueryBuilder @@ -56,7 +56,7 @@ namespace Lucene.Net.Util private bool enablePositionIncrements = true; /// <summary> - /// Creates a new QueryBuilder using the given analyzer. </summary> + /// Creates a new <see cref="QueryBuilder"/> using the given analyzer. </summary> public QueryBuilder(Analyzer analyzer) { this.analyzer = analyzer; @@ -64,12 +64,12 @@ namespace Lucene.Net.Util /// <summary> /// Creates a boolean query from the query text. - /// <p> - /// this is equivalent to {@code createBooleanQuery(field, queryText, Occur.SHOULD)} </summary> - /// <param name="field"> field name </param> - /// <param name="queryText"> text to be passed to the analyzer </param> - /// <returns> {@code TermQuery} or {@code BooleanQuery}, based on the analysis - /// of {@code queryText} </returns> + /// <para/> + /// This is equivalent to <c>CreateBooleanQuery(field, queryText, Occur.SHOULD)</c> </summary> + /// <param name="field"> Field name. </param> + /// <param name="queryText"> Text to be passed to the analyzer. </param> + /// <returns> <see cref="TermQuery"/> or <see cref="BooleanQuery"/>, based on the analysis + /// of <paramref name="queryText"/>. </returns> public virtual Query CreateBooleanQuery(string field, string queryText) { return CreateBooleanQuery(field, queryText, Occur.SHOULD); @@ -77,12 +77,12 @@ namespace Lucene.Net.Util /// <summary> /// Creates a boolean query from the query text. - /// <p> </summary> - /// <param name="field"> field name </param> - /// <param name="queryText"> text to be passed to the analyzer </param> - /// <param name="operator"> operator used for clauses between analyzer tokens. </param> - /// <returns> {@code TermQuery} or {@code BooleanQuery}, based on the analysis - /// of {@code queryText} </returns> + /// </summary> + /// <param name="field"> Field name </param> + /// <param name="queryText"> Text to be passed to the analyzer. </param> + /// <param name="operator"> Operator used for clauses between analyzer tokens. </param> + /// <returns> <see cref="TermQuery"/> or <see cref="BooleanQuery"/>, based on the analysis + /// of <paramref name="queryText"/>. </returns> public virtual Query CreateBooleanQuery(string field, string queryText, Occur @operator) { if (@operator != Occur.SHOULD && @operator != Occur.MUST) @@ -94,12 +94,12 @@ namespace Lucene.Net.Util /// <summary> /// Creates a phrase query from the query text. - /// <p> - /// this is equivalent to {@code createPhraseQuery(field, queryText, 0)} </summary> - /// <param name="field"> field name </param> - /// <param name="queryText"> text to be passed to the analyzer </param> - /// <returns> {@code TermQuery}, {@code BooleanQuery}, {@code PhraseQuery}, or - /// {@code MultiPhraseQuery}, based on the analysis of {@code queryText} </returns> + /// <para/> + /// This is equivalent to <c>CreatePhraseQuery(field, queryText, 0)</c> </summary> + /// <param name="field"> Field name. </param> + /// <param name="queryText"> Text to be passed to the analyzer. </param> + /// <returns> <see cref="TermQuery"/>, <see cref="BooleanQuery"/>, <see cref="PhraseQuery"/>, or + /// <see cref="MultiPhraseQuery"/>, based on the analysis of <paramref name="queryText"/>. </returns> public virtual Query CreatePhraseQuery(string field, string queryText) { return CreatePhraseQuery(field, queryText, 0); @@ -107,12 +107,12 @@ namespace Lucene.Net.Util /// <summary> /// Creates a phrase query from the query text. - /// <p> </summary> - /// <param name="field"> field name </param> - /// <param name="queryText"> text to be passed to the analyzer </param> + /// </summary> + /// <param name="field"> Field name. </param> + /// <param name="queryText"> Text to be passed to the analyzer. </param> /// <param name="phraseSlop"> number of other words permitted between words in query phrase </param> - /// <returns> {@code TermQuery}, {@code BooleanQuery}, {@code PhraseQuery}, or - /// {@code MultiPhraseQuery}, based on the analysis of {@code queryText} </returns> + /// <returns> <see cref="TermQuery"/>, <see cref="BooleanQuery"/>, <see cref="PhraseQuery"/>, or + /// <see cref="MultiPhraseQuery"/>, based on the analysis of <paramref name="queryText"/>. </returns> public virtual Query CreatePhraseQuery(string field, string queryText, int phraseSlop) { return CreateFieldQuery(analyzer, Occur.MUST, field, queryText, true, phraseSlop); @@ -120,12 +120,12 @@ namespace Lucene.Net.Util /// <summary> /// Creates a minimum-should-match query from the query text. - /// <p> </summary> - /// <param name="field"> field name </param> - /// <param name="queryText"> text to be passed to the analyzer </param> + /// </summary> + /// <param name="field"> Field name. </param> + /// <param name="queryText"> Text to be passed to the analyzer. </param> /// <param name="fraction"> of query terms {@code [0..1]} that should match </param> - /// <returns> {@code TermQuery} or {@code BooleanQuery}, based on the analysis - /// of {@code queryText} </returns> + /// <returns> <see cref="TermQuery"/> or <see cref="BooleanQuery"/>, based on the analysis + /// of <paramref name="queryText"/>. </returns> public virtual Query CreateMinShouldMatchQuery(string field, string queryText, float fraction) { if (float.IsNaN(fraction) || fraction < 0 || fraction > 1) @@ -149,8 +149,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns the analyzer. </summary> - /// <seealso cref= #setAnalyzer(Analyzer) </seealso> + /// Gets or Sets the analyzer. </summary> public virtual Analyzer Analyzer { get @@ -164,8 +163,15 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns true if position increments are enabled. </summary> - /// <seealso cref= #setEnablePositionIncrements(boolean) </seealso> + /// Gets or Sets whether position increments are enabled. + /// <para/> + /// When <c>true</c>, result phrase and multi-phrase queries will + /// be aware of position increments. + /// Useful when e.g. a StopFilter increases the position increment of + /// the token that follows an omitted token. + /// <para/> + /// Default: true. + /// </summary> public virtual bool EnablePositionIncrements { get @@ -180,16 +186,16 @@ namespace Lucene.Net.Util /// <summary> /// Creates a query from the analysis chain. - /// <p> + /// <para/> /// Expert: this is more useful for subclasses such as queryparsers. - /// If using this class directly, just use <seealso cref="#createBooleanQuery(String, String)"/> - /// and <seealso cref="#createPhraseQuery(String, String)"/> </summary> - /// <param name="analyzer"> analyzer used for this query </param> - /// <param name="operator"> default boolean operator used for this query </param> - /// <param name="field"> field to create queries against </param> - /// <param name="queryText"> text to be passed to the analysis chain </param> - /// <param name="quoted"> true if phrases should be generated when terms occur at more than one position </param> - /// <param name="phraseSlop"> slop factor for phrase/multiphrase queries </param> + /// If using this class directly, just use <see cref="CreateBooleanQuery(string, string)"/> + /// and <see cref="CreatePhraseQuery(string, string)"/>. </summary> + /// <param name="analyzer"> Analyzer used for this query. </param> + /// <param name="operator"> Default boolean operator used for this query. </param> + /// <param name="field"> Field to create queries against. </param> + /// <param name="queryText"> Text to be passed to the analysis chain. </param> + /// <param name="quoted"> <c>true</c> if phrases should be generated when terms occur at more than one position. </param> + /// <param name="phraseSlop"> Slop factor for phrase/multiphrase queries. </param> protected Query CreateFieldQuery(Analyzer analyzer, Occur @operator, string field, string queryText, bool quoted, int phraseSlop) { Debug.Assert(@operator == Occur.SHOULD || @operator == Occur.MUST); @@ -439,42 +445,46 @@ namespace Lucene.Net.Util } /// <summary> - /// Builds a new BooleanQuery instance. - /// <p> - /// this is intended for subclasses that wish to customize the generated queries. </summary> - /// <param name="disableCoord"> disable coord </param> - /// <returns> new BooleanQuery instance </returns> + /// Builds a new <see cref="BooleanQuery"/> instance. + /// <para/> + /// This is intended for subclasses that wish to customize the generated queries. + /// </summary> + /// <param name="disableCoord"> Disable coord. </param> + /// <returns> New <see cref="BooleanQuery"/> instance. </returns> protected virtual BooleanQuery NewBooleanQuery(bool disableCoord) { return new BooleanQuery(disableCoord); } /// <summary> - /// Builds a new TermQuery instance. - /// <p> - /// this is intended for subclasses that wish to customize the generated queries. </summary> - /// <param name="term"> term </param> - /// <returns> new TermQuery instance </returns> + /// Builds a new <see cref="TermQuery"/> instance. + /// <para/> + /// This is intended for subclasses that wish to customize the generated queries. + /// </summary> + /// <param name="term"> Term. </param> + /// <returns> New <see cref="TermQuery"/> instance. </returns> protected virtual Query NewTermQuery(Term term) { return new TermQuery(term); } /// <summary> - /// Builds a new PhraseQuery instance. - /// <p> - /// this is intended for subclasses that wish to customize the generated queries. </summary> - /// <returns> new PhraseQuery instance </returns> + /// Builds a new <see cref="PhraseQuery"/> instance. + /// <para/> + /// This is intended for subclasses that wish to customize the generated queries. + /// </summary> + /// <returns> New <see cref="PhraseQuery"/> instance. </returns> protected virtual PhraseQuery NewPhraseQuery() { return new PhraseQuery(); } /// <summary> - /// Builds a new MultiPhraseQuery instance. - /// <p> - /// this is intended for subclasses that wish to customize the generated queries. </summary> - /// <returns> new MultiPhraseQuery instance </returns> + /// Builds a new <see cref="MultiPhraseQuery"/> instance. + /// <para/> + /// This is intended for subclasses that wish to customize the generated queries. + /// </summary> + /// <returns> New <see cref="MultiPhraseQuery"/> instance. </returns> protected virtual MultiPhraseQuery NewMultiPhraseQuery() { return new MultiPhraseQuery(); http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/RamUsageEstimator.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/RamUsageEstimator.cs b/src/Lucene.Net/Util/RamUsageEstimator.cs index 6e0fca7..5ae74a8 100644 --- a/src/Lucene.Net/Util/RamUsageEstimator.cs +++ b/src/Lucene.Net/Util/RamUsageEstimator.cs @@ -27,13 +27,13 @@ namespace Lucene.Net.Util */ /// <summary> - /// Estimates the size (memory representation) of Java objects. + /// Estimates the size (memory representation) of .NET objects. + /// <para/> + /// @lucene.internal /// </summary> - /// <seealso cref= #sizeOf(Object) </seealso> - /// <seealso cref= #shallowSizeOf(Object) </seealso> - /// <seealso cref= #shallowSizeOfInstance(Class) - /// - /// @lucene.internal </seealso> + /// <seealso cref="SizeOf(object)"/> + /// <seealso cref="ShallowSizeOf(object)"/> + /// <seealso cref="ShallowSizeOfInstance(Type)"/> public sealed class RamUsageEstimator { ///// <summary> @@ -84,7 +84,7 @@ namespace Lucene.Net.Util public const int NUM_BYTES_DOUBLE = 8; /// <summary> - /// Number of bytes this jvm uses to represent an object reference. + /// Number of bytes this .NET runtime uses to represent an object reference. /// </summary> public static readonly int NUM_BYTES_OBJECT_REF; @@ -99,7 +99,7 @@ namespace Lucene.Net.Util public static readonly int NUM_BYTES_ARRAY_HEADER; /// <summary> - /// A constant specifying the object alignment boundary inside the JVM. Objects will + /// A constant specifying the object alignment boundary inside the .NET runtime. Objects will /// always take a full multiple of this constant, possibly wasting some space. /// </summary> public static readonly int NUM_BYTES_OBJECT_ALIGNMENT; @@ -234,14 +234,14 @@ namespace Lucene.Net.Util //JVM_INFO_STRING = "[JVM: " + Constants.JVM_NAME + ", " + Constants.JVM_VERSION + ", " + Constants.JVM_VENDOR + ", " + Constants.JAVA_VENDOR + ", " + Constants.JAVA_VERSION + "]"; } - /// <summary> - /// A handle to <code>sun.misc.Unsafe</code>. - /// </summary> + ///// <summary> + ///// A handle to <code>sun.misc.Unsafe</code>. + ///// </summary> //private static readonly object TheUnsafe; - /// <summary> - /// A handle to <code>sun.misc.Unsafe#fieldOffset(Field)</code>. - /// </summary> + ///// <summary> + ///// A handle to <code>sun.misc.Unsafe#fieldOffset(Field)</code>. + ///// </summary> //private static readonly Method ObjectFieldOffsetMethod; /// <summary> @@ -276,7 +276,7 @@ namespace Lucene.Net.Util //} /// <summary> - /// Aligns an object size to be the next multiple of <seealso cref="#NUM_BYTES_OBJECT_ALIGNMENT"/>. + /// Aligns an object size to be the next multiple of <see cref="NUM_BYTES_OBJECT_ALIGNMENT"/>. /// </summary> public static long AlignObjectSize(long size) { @@ -285,7 +285,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns the size in bytes of the byte[] object. </summary> + /// Returns the size in bytes of the <see cref="T:byte[]"/> object. </summary> // LUCENENET specific overload for CLS compliance public static long SizeOf(byte[] arr) { @@ -293,7 +293,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns the size in bytes of the sbyte[] object. </summary> + /// Returns the size in bytes of the <see cref="T:sbyte[]"/> object. </summary> [CLSCompliant(false)] public static long SizeOf(sbyte[] arr) { @@ -301,62 +301,64 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns the size in bytes of the boolean[] object. </summary> + /// Returns the size in bytes of the <see cref="T:bool[]"/> object. </summary> public static long SizeOf(bool[] arr) { return AlignObjectSize((long)NUM_BYTES_ARRAY_HEADER + arr.Length); } /// <summary> - /// Returns the size in bytes of the char[] object. </summary> + /// Returns the size in bytes of the <see cref="T:char[]"/> object. </summary> public static long SizeOf(char[] arr) { return AlignObjectSize((long)NUM_BYTES_ARRAY_HEADER + (long)NUM_BYTES_CHAR * arr.Length); } /// <summary> - /// Returns the size in bytes of the short[] object. </summary> + /// Returns the size in bytes of the <see cref="T:short[]"/> object. </summary> public static long SizeOf(short[] arr) { return AlignObjectSize((long)NUM_BYTES_ARRAY_HEADER + (long)NUM_BYTES_INT16 * arr.Length); } /// <summary> - /// Returns the size in bytes of the int[] object. </summary> + /// Returns the size in bytes of the <see cref="T:int[]"/> object. </summary> public static long SizeOf(int[] arr) { return AlignObjectSize((long)NUM_BYTES_ARRAY_HEADER + (long)NUM_BYTES_INT32 * arr.Length); } /// <summary> - /// Returns the size in bytes of the float[] object. </summary> + /// Returns the size in bytes of the <see cref="T:float[]"/> object. </summary> public static long SizeOf(float[] arr) { return AlignObjectSize((long)NUM_BYTES_ARRAY_HEADER + (long)NUM_BYTES_SINGLE * arr.Length); } /// <summary> - /// Returns the size in bytes of the long[] object. </summary> + /// Returns the size in bytes of the <see cref="T:long[]"/> object. </summary> public static long SizeOf(long[] arr) { return AlignObjectSize((long)NUM_BYTES_ARRAY_HEADER + (long)NUM_BYTES_INT64 * arr.Length); } /// <summary> - /// Returns the size in bytes of the double[] object. </summary> + /// Returns the size in bytes of the <see cref="T:double[]"/> object. </summary> public static long SizeOf(double[] arr) { return AlignObjectSize((long)NUM_BYTES_ARRAY_HEADER + (long)NUM_BYTES_DOUBLE * arr.Length); } + // LUCENENET TODO: API - Add SizeOf() overloads for ulong, ushort, uint + /// <summary> /// Estimates the RAM usage by the given object. It will /// walk the object tree and sum up all referenced objects. /// - /// <p><b>Resource Usage:</b> this method internally uses a set of + /// <para><b>Resource Usage:</b> this method internally uses a set of /// every object seen during traversals so it does allocate memory /// (it isn't side-effect free). After the method exits, this memory - /// should be GCed.</p> + /// should be GCed.</para> /// </summary> public static long SizeOf(object obj) { @@ -367,8 +369,8 @@ namespace Lucene.Net.Util /// Estimates a "shallow" memory usage of the given object. For arrays, this will be the /// memory taken by array storage (no subreferences will be followed). For objects, this /// will be the memory taken by the fields. - /// - /// JVM object alignments are also applied. + /// <para/> + /// .NET object alignments are also applied. /// </summary> public static long ShallowSizeOf(object obj) { @@ -389,11 +391,11 @@ namespace Lucene.Net.Util /// <summary> /// Returns the shallow instance size in bytes an instance of the given class would occupy. - /// this works with all conventional classes and primitive types, but not with arrays + /// This works with all conventional classes and primitive types, but not with arrays /// (the size then depends on the number of elements and varies from object to object). /// </summary> - /// <seealso cref= #shallowSizeOf(Object) </seealso> - /// <exception cref="IllegalArgumentException"> if {@code clazz} is an array class. </exception> + /// <seealso cref="ShallowSizeOf(object)"/> + /// <exception cref="ArgumentException"> if <paramref name="clazz"/> is an array class. </exception> public static long ShallowSizeOfInstance(Type clazz) { if (clazz.IsArray) @@ -428,7 +430,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Return shallow size of any <code>array</code>. + /// Return shallow size of any <paramref name="array"/>. /// </summary> private static long ShallowSizeOfArray(Array array) { @@ -597,11 +599,11 @@ namespace Lucene.Net.Util } /// <summary> - /// this method returns the maximum representation size of an object. <code>sizeSoFar</code> - /// is the object's size measured so far. <code>f</code> is the field being probed. + /// This method returns the maximum representation size of an object. <paramref name="sizeSoFar"/> + /// is the object's size measured so far. <paramref name="f"/> is the field being probed. /// - /// <p>The returned offset will be the maximum of whatever was measured so far and - /// <code>f</code> field's offset and representation size (unaligned). + /// <para/>The returned offset will be the maximum of whatever was measured so far and + /// <paramref name="f"/> field's offset and representation size (unaligned). /// </summary> private static long AdjustForField(long sizeSoFar, FieldInfo f) { @@ -629,7 +631,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns <code>size</code> in human-readable units (GB, MB, KB or bytes). + /// Returns <c>size</c> in human-readable units (GB, MB, KB or bytes). /// </summary> public static string HumanReadableUnits(long bytes) { @@ -637,7 +639,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns <code>size</code> in human-readable units (GB, MB, KB or bytes). + /// Returns <c>size</c> in human-readable units (GB, MB, KB or bytes). /// </summary> public static string HumanReadableUnits(long bytes, IFormatProvider df) { @@ -661,8 +663,8 @@ namespace Lucene.Net.Util /// <summary> /// Return a human-readable size of a given object. </summary> - /// <seealso cref= #sizeOf(Object) </seealso> - /// <seealso cref= #humanReadableUnits(long) </seealso> + /// <seealso cref="SizeOf(object)"/> + /// <seealso cref="HumanReadableUnits(long)"/> public static string HumanSizeOf(object @object) { return HumanReadableUnits(SizeOf(@object)); @@ -670,10 +672,10 @@ namespace Lucene.Net.Util /// <summary> /// An identity hash set implemented using open addressing. No null keys are allowed. - /// + /// <para/> /// TODO: If this is useful outside this class, make it public - needs some work /// </summary> - public sealed class IdentityHashSet<KType> : IEnumerable<KType> + public sealed class IdentityHashSet<KType> : IEnumerable<KType> // LUCENENET TODO: API - This was internal in Lucene { /// <summary> /// Default load factor. @@ -714,8 +716,8 @@ namespace Lucene.Net.Util private int resizeThreshold; /// <summary> - /// Creates a hash set with the default capacity of 16. - /// load factor of {@value #DEFAULT_LOAD_FACTOR}. ` + /// Creates a hash set with the default capacity of 16, + /// load factor of <see cref="DEFAULT_LOAD_FACTOR"/>. /// </summary> public IdentityHashSet() : this(16, DEFAULT_LOAD_FACTOR) @@ -724,7 +726,7 @@ namespace Lucene.Net.Util /// <summary> /// Creates a hash set with the given capacity, load factor of - /// {@value #DEFAULT_LOAD_FACTOR}. + /// <see cref="DEFAULT_LOAD_FACTOR"/>. /// </summary> public IdentityHashSet(int initialCapacity) : this(initialCapacity, DEFAULT_LOAD_FACTOR) @@ -794,11 +796,12 @@ namespace Lucene.Net.Util /// <summary> /// Rehash via MurmurHash. /// - /// <p>The implementation is based on the + /// <para/>The implementation is based on the /// finalization step from Austin Appleby's - /// <code>MurmurHash3</code>. + /// <c>MurmurHash3</c>. + /// + /// See <a target="_blank" href="http://sites.google.com/site/murmurhash/";>http://sites.google.com/site/murmurhash/</a>. /// </summary> - /// <seealso cref= "http://sites.google.com/site/murmurhash/"; </seealso> private static int Rehash(object o) { int k = RuntimeHelpers.GetHashCode(o); @@ -842,7 +845,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Allocate internal buffers for a given capacity. + /// Allocate internal buffers for a given <paramref name="capacity"/>. /// </summary> /// <param name="capacity"> /// New capacity (must be a power of two). </param> @@ -898,6 +901,8 @@ namespace Lucene.Net.Util get { return Assigned; } } + // LUCENENET TODO: API - bring back this IsEmpty property (doesn't work the same as !Any()) + //public bool Empty // LUCENENET NOTE: in .NET we can just use !Any() on IEnumerable<T> //{ // get http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/RecyclingByteBlockAllocator.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/RecyclingByteBlockAllocator.cs b/src/Lucene.Net/Util/RecyclingByteBlockAllocator.cs index f92aa3f..d423f29 100644 --- a/src/Lucene.Net/Util/RecyclingByteBlockAllocator.cs +++ b/src/Lucene.Net/Util/RecyclingByteBlockAllocator.cs @@ -21,12 +21,12 @@ namespace Lucene.Net.Util */ /// <summary> - /// A <seealso cref="ByteBlockPool.Allocator"/> implementation that recycles unused byte + /// A <see cref="ByteBlockPool.Allocator"/> implementation that recycles unused byte /// blocks in a buffer and reuses them in subsequent calls to - /// <seealso cref="#getByteBlock()"/>. - /// <p> - /// Note: this class is not thread-safe - /// </p> + /// <see cref="GetByteBlock()"/>. + /// <para> + /// Note: this class is not thread-safe. + /// </para> /// @lucene.internal /// </summary> public sealed class RecyclingByteBlockAllocator : ByteBlockPool.Allocator @@ -38,14 +38,14 @@ namespace Lucene.Net.Util public const int DEFAULT_BUFFERED_BLOCKS = 64; /// <summary> - /// Creates a new <seealso cref="RecyclingByteBlockAllocator"/> + /// Creates a new <see cref="RecyclingByteBlockAllocator"/> /// </summary> /// <param name="blockSize"> - /// the block size in bytes </param> + /// The block size in bytes. </param> /// <param name="maxBufferedBlocks"> - /// maximum number of buffered byte block </param> + /// Maximum number of buffered byte block. </param> /// <param name="bytesUsed"> - /// <seealso cref="Counter"/> reference counting internally allocated bytes </param> + /// <see cref="Counter"/> reference counting internally allocated bytes. </param> public RecyclingByteBlockAllocator(int blockSize, int maxBufferedBlocks, Counter bytesUsed) : base(blockSize) { @@ -55,22 +55,21 @@ namespace Lucene.Net.Util } /// <summary> - /// Creates a new <seealso cref="RecyclingByteBlockAllocator"/>. + /// Creates a new <see cref="RecyclingByteBlockAllocator"/>. /// </summary> /// <param name="blockSize"> - /// the block size in bytes </param> + /// The block size in bytes. </param> /// <param name="maxBufferedBlocks"> - /// maximum number of buffered byte block </param> + /// Maximum number of buffered byte block. </param> public RecyclingByteBlockAllocator(int blockSize, int maxBufferedBlocks) : this(blockSize, maxBufferedBlocks, Counter.NewCounter(false)) { } /// <summary> - /// Creates a new <seealso cref="RecyclingByteBlockAllocator"/> with a block size of - /// <seealso cref="ByteBlockPool#BYTE_BLOCK_SIZE"/>, upper buffered docs limit of - /// <seealso cref="#DEFAULT_BUFFERED_BLOCKS"/> ({@value #DEFAULT_BUFFERED_BLOCKS}). - /// + /// Creates a new <see cref="RecyclingByteBlockAllocator"/> with a block size of + /// <see cref="ByteBlockPool.BYTE_BLOCK_SIZE"/>, upper buffered docs limit of + /// <see cref="DEFAULT_BUFFERED_BLOCKS"/> (64). /// </summary> public RecyclingByteBlockAllocator() : this(ByteBlockPool.BYTE_BLOCK_SIZE, 64, Counter.NewCounter(false)) @@ -113,19 +112,19 @@ namespace Lucene.Net.Util Debug.Assert(bytesUsed.Get() >= 0); } - /// <returns> the number of currently buffered blocks </returns> + /// <returns> The number of currently buffered blocks. </returns> public int NumBufferedBlocks { get { return freeBlocks; } } - /// <returns> the number of bytes currently allocated by this <seealso cref="Allocator"/> </returns> + /// <returns> The number of bytes currently allocated by this <see cref="ByteBlockPool.Allocator"/>. </returns> public long BytesUsed { get { return bytesUsed.Get(); } } - /// <returns> the maximum number of buffered byte blocks </returns> + /// <returns> The maximum number of buffered byte blocks. </returns> public int MaxBufferedBlocks { get { return maxBufferedBlocks; } @@ -135,8 +134,8 @@ namespace Lucene.Net.Util /// Removes the given number of byte blocks from the buffer if possible. /// </summary> /// <param name="num"> - /// the number of byte blocks to remove </param> - /// <returns> the number of actually removed buffers </returns> + /// The number of byte blocks to remove. </param> + /// <returns> The number of actually removed buffers. </returns> public int FreeBlocks(int num) { Debug.Assert(num >= 0, "free blocks must be >= 0 but was: " + num); http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/RecyclingIntBlockAllocator.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/RecyclingIntBlockAllocator.cs b/src/Lucene.Net/Util/RecyclingIntBlockAllocator.cs index 073ea2d..9547e42 100644 --- a/src/Lucene.Net/Util/RecyclingIntBlockAllocator.cs +++ b/src/Lucene.Net/Util/RecyclingIntBlockAllocator.cs @@ -23,11 +23,11 @@ namespace Lucene.Net.Util using Allocator = Lucene.Net.Util.Int32BlockPool.Allocator; /// <summary> - /// A <seealso cref="Allocator"/> implementation that recycles unused int + /// A <see cref="Allocator"/> implementation that recycles unused <see cref="int"/> /// blocks in a buffer and reuses them in subsequent calls to - /// <seealso cref="#getIntBlock()"/>. + /// <see cref="GetInt32Block()"/>. /// <para> - /// Note: this class is not thread-safe + /// Note: this class is not thread-safe. /// </para> /// <para> /// NOTE: This was RecyclingIntBlockAllocator in Lucene @@ -43,14 +43,14 @@ namespace Lucene.Net.Util public const int DEFAULT_BUFFERED_BLOCKS = 64; /// <summary> - /// Creates a new <seealso cref="RecyclingInt32BlockAllocator"/> + /// Creates a new <see cref="RecyclingInt32BlockAllocator"/>. /// </summary> /// <param name="blockSize"> - /// the block size in bytes </param> + /// The block size in bytes. </param> /// <param name="maxBufferedBlocks"> - /// maximum number of buffered int block </param> + /// Maximum number of buffered int block. </param> /// <param name="bytesUsed"> - /// <seealso cref="Counter"/> reference counting internally allocated bytes </param> + /// <see cref="Counter"/> reference counting internally allocated bytes. </param> public RecyclingInt32BlockAllocator(int blockSize, int maxBufferedBlocks, Counter bytesUsed) : base(blockSize) { @@ -60,12 +60,12 @@ namespace Lucene.Net.Util } /// <summary> - /// Creates a new <seealso cref="RecyclingInt32BlockAllocator"/>. + /// Creates a new <see cref="RecyclingInt32BlockAllocator"/>. /// </summary> /// <param name="blockSize"> - /// the size of each block returned by this allocator </param> + /// The size of each block returned by this allocator. </param> /// <param name="maxBufferedBlocks"> - /// maximum number of buffered int blocks </param> + /// Maximum number of buffered int blocks. </param> public RecyclingInt32BlockAllocator(int blockSize, int maxBufferedBlocks) : this(blockSize, maxBufferedBlocks, Counter.NewCounter(false)) { @@ -75,7 +75,6 @@ namespace Lucene.Net.Util /// Creates a new <see cref="RecyclingInt32BlockAllocator"/> with a block size of /// <see cref="Int32BlockPool.INT32_BLOCK_SIZE"/>, upper buffered docs limit of /// <see cref="DEFAULT_BUFFERED_BLOCKS"/>. - /// /// </summary> public RecyclingInt32BlockAllocator() : this(Int32BlockPool.INT32_BLOCK_SIZE, 64, Counter.NewCounter(false)) @@ -124,19 +123,19 @@ namespace Lucene.Net.Util Debug.Assert(bytesUsed.Get() >= 0); } - /// <returns> the number of currently buffered blocks </returns> + /// <returns> The number of currently buffered blocks. </returns> public int NumBufferedBlocks { get { return freeBlocks; } } - /// <returns> the number of bytes currently allocated by this <seealso cref="Allocator"/> </returns> + /// <returns> The number of bytes currently allocated by this <see cref="Allocator"/>. </returns> public long BytesUsed { get { return bytesUsed.Get(); } } - /// <returns> the maximum number of buffered byte blocks </returns> + /// <returns> The maximum number of buffered byte blocks. </returns> public int MaxBufferedBlocks { get { return maxBufferedBlocks; } @@ -146,8 +145,8 @@ namespace Lucene.Net.Util /// Removes the given number of int blocks from the buffer if possible. /// </summary> /// <param name="num"> - /// the number of int blocks to remove </param> - /// <returns> the number of actually removed buffers </returns> + /// The number of int blocks to remove. </param> + /// <returns> The number of actually removed buffers. </returns> public int FreeBlocks(int num) { Debug.Assert(num >= 0, "free blocks must be >= 0 but was: " + num); http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/RollingBuffer.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/RollingBuffer.cs b/src/Lucene.Net/Util/RollingBuffer.cs index defd7c7..e28c30a 100644 --- a/src/Lucene.Net/Util/RollingBuffer.cs +++ b/src/Lucene.Net/Util/RollingBuffer.cs @@ -20,8 +20,15 @@ namespace Lucene.Net.Util * limitations under the License. */ + /// <summary> + /// LUCENENET specific class to allow referencing static members of + /// <see cref="RollingBuffer{T}"/> without referencing its generic closing type. + /// </summary> public static class RollingBuffer { + /// <summary> + /// Implement to reset an instance + /// </summary> public interface IResettable { void Reset(); @@ -29,10 +36,10 @@ namespace Lucene.Net.Util } /// <summary> - /// Acts like forever growing T[], but internally uses a - /// circular buffer to reuse instances of T. - /// - /// @lucene.internal + /// Acts like forever growing <see cref="T:T[]"/>, but internally uses a + /// circular buffer to reuse instances of <typeparam name="T"/>. + /// <para/> + /// @lucene.internal /// </summary> public abstract class RollingBuffer<T> where T : RollingBuffer.IResettable @@ -101,9 +108,9 @@ namespace Lucene.Net.Util } /// <summary> - /// Get T instance for this absolute position; - /// this is allowed to be arbitrarily far "in the - /// future" but cannot be before the last freeBefore. + /// Get <typeparamref name="T"/> instance for this absolute position; + /// This is allowed to be arbitrarily far "in the + /// future" but cannot be before the last <see cref="FreeBefore(int)"/>. /// </summary> public virtual T Get(int pos) { @@ -138,7 +145,7 @@ namespace Lucene.Net.Util /// <summary> /// Returns the maximum position looked up, or -1 if no - /// position has been looked up sinc reset/init. + /// position has been looked up since <see cref="Reset()"/>/init. /// </summary> public virtual int MaxPos { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/SPIClassIterator.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/SPIClassIterator.cs b/src/Lucene.Net/Util/SPIClassIterator.cs index a2a3f02..8a75309 100644 --- a/src/Lucene.Net/Util/SPIClassIterator.cs +++ b/src/Lucene.Net/Util/SPIClassIterator.cs @@ -27,13 +27,12 @@ namespace Lucene.Net.Util /// <summary> /// Helper class for loading SPI classes from classpath (META-INF files). - /// this is a light impl of <seealso cref="java.util.ServiceLoader"/> but is guaranteed to + /// This is a light impl of <c>java.util.ServiceLoader</c> but is guaranteed to /// be bug-free regarding classpath order and does not instantiate or initialize /// the classes found. - /// + /// <para/> /// @lucene.internal /// </summary> - /// public class SPIClassIterator<S> : IEnumerable<Type> { private static HashSet<Type> types; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/SentinelIntSet.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/SentinelIntSet.cs b/src/Lucene.Net/Util/SentinelIntSet.cs index 079c212..d908c9c 100644 --- a/src/Lucene.Net/Util/SentinelIntSet.cs +++ b/src/Lucene.Net/Util/SentinelIntSet.cs @@ -23,23 +23,25 @@ namespace Lucene.Net.Util */ /// <summary> - /// A native int hash-based set where one value is reserved to mean "EMPTY" internally. The space overhead is fairly low - /// as there is only one power-of-two sized int[] to hold the values. The set is re-hashed when adding a value that - /// would make it >= 75% full. Consider extending and over-riding <seealso cref="#hash(int)"/> if the values might be poor + /// A native <see cref="int"/> hash-based set where one value is reserved to mean "EMPTY" internally. The space overhead is fairly low + /// as there is only one power-of-two sized <see cref="T:int[]"/> to hold the values. The set is re-hashed when adding a value that + /// would make it >= 75% full. Consider extending and over-riding <see cref="Hash(int)"/> if the values might be poor /// hash keys; Lucene docids should be fine. /// The internal fields are exposed publicly to enable more efficient use at the expense of better O-O principles. /// <para/> /// To iterate over the integers held in this set, simply use code like this: /// <code> /// SentinelIntSet set = ... - /// for (int v : set.keys) { - /// if (v == set.emptyVal) - /// continue; - /// //use v... - /// }</code> + /// foreach (int v in set.keys) + /// { + /// if (v == set.EmptyVal) + /// continue; + /// //use v... + /// } + /// </code> /// <para/> /// NOTE: This was SentinelIntSet in Lucene - /// + /// <para/> /// @lucene.internal /// </summary> public class SentinelInt32Set @@ -61,13 +63,13 @@ namespace Lucene.Net.Util public int EmptyVal { get; private set; } /// <summary> - /// the count at which a rehash should be done </summary> + /// The count at which a rehash should be done. </summary> public int RehashCount { get; set; } /// /// <param name="size"> The minimum number of elements this set should be able to hold without rehashing - /// (i.e. the slots are guaranteed not to change) </param> - /// <param name="emptyVal"> The integer value to use for EMPTY </param> + /// (i.e. the slots are guaranteed not to change). </param> + /// <param name="emptyVal"> The integer value to use for EMPTY. </param> public SentinelInt32Set(int size, int emptyVal) { this.EmptyVal = emptyVal; @@ -109,7 +111,7 @@ namespace Lucene.Net.Util //} /// <summary> - /// (internal) Returns the slot for this key </summary> + /// (internal) Returns the slot for this key. </summary> public virtual int GetSlot(int key) { Debug.Assert(key != EmptyVal); @@ -129,7 +131,7 @@ namespace Lucene.Net.Util } /// <summary> - /// (internal) Returns the slot for this key, or -slot-1 if not found </summary> + /// (internal) Returns the slot for this key, or -slot-1 if not found. </summary> public virtual int Find(int key) { Debug.Assert(key != EmptyVal); @@ -191,7 +193,7 @@ namespace Lucene.Net.Util } /// <summary> - /// (internal) Rehashes by doubling {@code int[] key} and filling with the old values. </summary> + /// (internal) Rehashes by doubling key (<see cref="T:int[]"/>) and filling with the old values. </summary> public virtual void Rehash() { int newSize = keys.Length << 1; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/SetOnce.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/SetOnce.cs b/src/Lucene.Net/Util/SetOnce.cs index 63c1b1d..cc74d54 100644 --- a/src/Lucene.Net/Util/SetOnce.cs +++ b/src/Lucene.Net/Util/SetOnce.cs @@ -96,6 +96,9 @@ namespace Lucene.Net.Util #endif public sealed class AlreadySetException : InvalidOperationException { + /// <summary> + /// Initializes a new instance of <see cref="AlreadySetException"/>. + /// </summary> public AlreadySetException() : base("The object cannot be set twice!") { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/SloppyMath.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/SloppyMath.cs b/src/Lucene.Net/Util/SloppyMath.cs index 295e842..e7a3d09 100644 --- a/src/Lucene.Net/Util/SloppyMath.cs +++ b/src/Lucene.Net/Util/SloppyMath.cs @@ -60,16 +60,17 @@ namespace Lucene.Net.Util /// <summary> /// Returns the trigonometric cosine of an angle. - /// <p> + /// <para/> /// Error is around 1E-15. - /// <p> + /// <para/> /// Special cases: - /// <ul> - /// <li>If the argument is {@code NaN} or an infinity, then the result is {@code NaN}. - /// </ul> </summary> - /// <param name="a"> an angle, in radians. </param> - /// <returns> the cosine of the argument. </returns> - /// <seealso cref= Math#cos(double) </seealso> + /// <list type="bullet"> + /// <item><description>If the argument is <see cref="double.NaN"/> or an infinity, then the result is <see cref="double.NaN"/>.</description></item> + /// </list> + /// </summary> + /// <param name="a"> An angle, in radians. </param> + /// <returns> The cosine of the argument. </returns> + /// <seealso cref="Math.Cos(double)"/> public static double Cos(double a) { if (a < 0.0) @@ -93,17 +94,18 @@ namespace Lucene.Net.Util /// <summary> /// Returns the arc sine of a value. - /// <p> + /// <para/> /// The returned angle is in the range <i>-pi</i>/2 through <i>pi</i>/2. /// Error is around 1E-7. - /// <p> + /// <para/> /// Special cases: - /// <ul> - /// <li>If the argument is {@code NaN} or its absolute value is greater than 1, then the result is {@code NaN}. - /// </ul> </summary> + /// <list type="bullet"> + /// <item><description>If the argument is <see cref="double.NaN"/> or its absolute value is greater than 1, then the result is <see cref="double.NaN"/>.</description></item> + /// </list> + /// </summary> /// <param name="a"> the value whose arc sine is to be returned. </param> /// <returns> arc sine of the argument </returns> - /// <seealso cref= Math#asin(double) </seealso> + /// <seealso cref="Math.Asin(double)"/> // because asin(-x) = -asin(x), asin(x) only needs to be computed on [0,1]. // ---> we only have to compute asin(x) on [0,1]. // For values not close to +-1, we use look-up tables; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/SmallFloat.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/SmallFloat.cs b/src/Lucene.Net/Util/SmallFloat.cs index 7eb3b07..cbad7ab 100644 --- a/src/Lucene.Net/Util/SmallFloat.cs +++ b/src/Lucene.Net/Util/SmallFloat.cs @@ -23,7 +23,7 @@ namespace Lucene.Net.Util /// Floating point numbers smaller than 32 bits. /// <para/> /// NOTE: This was SmallFloat in Lucene - /// + /// <para/> /// @lucene.internal /// </summary> public class SmallSingle @@ -36,15 +36,15 @@ namespace Lucene.Net.Util /// <summary> /// Converts a 32 bit <see cref="float"/> to an 8 bit <see cref="float"/>. - /// <br>Values less than zero are all mapped to zero. - /// <br>Values are truncated (rounded down) to the nearest 8 bit value. - /// <br>Values between zero and the smallest representable value + /// <para/>Values less than zero are all mapped to zero. + /// <para/>Values are truncated (rounded down) to the nearest 8 bit value. + /// <para/>Values between zero and the smallest representable value /// are rounded up. /// </summary> - /// <param name="f"> the 32 bit <see cref="float"/> to be converted to an 8 bit <see cref="float"/> (<see cref="byte"/>) </param> - /// <param name="numMantissaBits"> the number of mantissa bits to use in the byte, with the remainder to be used in the exponent </param> - /// <param name="zeroExp"> the zero-point in the range of exponent values </param> - /// <returns> the 8 bit float representation </returns> + /// <param name="f"> The 32 bit <see cref="float"/> to be converted to an 8 bit <see cref="float"/> (<see cref="byte"/>). </param> + /// <param name="numMantissaBits"> The number of mantissa bits to use in the byte, with the remainder to be used in the exponent. </param> + /// <param name="zeroExp"> The zero-point in the range of exponent values. </param> + /// <returns> The 8 bit float representation. </returns> // LUCENENET specific overload for CLS compliance public static byte SingleToByte(float f, int numMantissaBits, int zeroExp) { @@ -60,10 +60,10 @@ namespace Lucene.Net.Util /// <para/> /// NOTE: This was floatToByte() in Lucene /// </summary> - /// <param name="f"> the 32 bit <see cref="float"/> to be converted to an 8 bit <see cref="float"/> (<see cref="sbyte"/>) </param> - /// <param name="numMantissaBits"> the number of mantissa bits to use in the byte, with the remainder to be used in the exponent </param> - /// <param name="zeroExp"> the zero-point in the range of exponent values </param> - /// <returns> the 8 bit float representation </returns> + /// <param name="f"> The 32 bit <see cref="float"/> to be converted to an 8 bit <see cref="float"/> (<see cref="sbyte"/>). </param> + /// <param name="numMantissaBits"> The number of mantissa bits to use in the byte, with the remainder to be used in the exponent. </param> + /// <param name="zeroExp"> The zero-point in the range of exponent values. </param> + /// <returns> The 8 bit float representation. </returns> [CLSCompliant(false)] public static sbyte SingleToSByte(float f, int numMantissaBits, int zeroExp) { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/Sorter.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/Sorter.cs b/src/Lucene.Net/Util/Sorter.cs index 1819541..79d2321 100644 --- a/src/Lucene.Net/Util/Sorter.cs +++ b/src/Lucene.Net/Util/Sorter.cs @@ -21,6 +21,7 @@ namespace Lucene.Net.Util /// <summary> /// Base class for sorting algorithms implementations. + /// <para/> /// @lucene.internal /// </summary> public abstract class Sorter @@ -34,19 +35,19 @@ namespace Lucene.Net.Util } /// <summary> - /// Compare entries found in slots <code>i</code> and <code>j</code>. - /// The contract for the returned value is the same as - /// <seealso cref="Comparer#compare(Object, Object)"/>. + /// Compare entries found in slots <paramref name="i"/> and <paramref name="j"/>. + /// The contract for the returned value is the same as + /// <see cref="System.Collections.Generic.IComparer{T}.Compare(T, T)"/>. /// </summary> protected abstract int Compare(int i, int j); /// <summary> - /// Swap values at slots <code>i</code> and <code>j</code>. </summary> + /// Swap values at slots <paramref name="i"/> and <paramref name="j"/>. </summary> protected abstract void Swap(int i, int j); /// <summary> - /// Sort the slice which starts at <code>from</code> (inclusive) and ends at - /// <code>to</code> (exclusive). + /// Sort the slice which starts at <paramref name="from"/> (inclusive) and ends at + /// <paramref name="to"/> (exclusive). /// </summary> public abstract void Sort(int from, int to); http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/StringHelper.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/StringHelper.cs b/src/Lucene.Net/Util/StringHelper.cs index b0fd150..1e1ebc4 100644 --- a/src/Lucene.Net/Util/StringHelper.cs +++ b/src/Lucene.Net/Util/StringHelper.cs @@ -23,7 +23,7 @@ namespace Lucene.Net.Util /// <summary> /// Methods for manipulating strings. - /// + /// <para/> /// @lucene.internal /// </summary> public abstract class StringHelper @@ -42,11 +42,11 @@ namespace Lucene.Net.Util } /// <summary> - /// Compares two <seealso cref="BytesRef"/>, element by element, and returns the + /// Compares two <see cref="BytesRef"/>, element by element, and returns the /// number of elements common to both arrays. /// </summary> - /// <param name="left"> The first <seealso cref="BytesRef"/> to compare </param> - /// <param name="right"> The second <seealso cref="BytesRef"/> to compare </param> + /// <param name="left"> The first <see cref="BytesRef"/> to compare. </param> + /// <param name="right"> The second <see cref="BytesRef"/> to compare. </param> /// <returns> The number of common elements. </returns> public static int BytesDifference(BytesRef left, BytesRef right) { @@ -69,8 +69,10 @@ namespace Lucene.Net.Util { } - /// <returns> a Comparer over versioned strings such as X.YY.Z - /// @lucene.internal </returns> + /// <summary> Returns a <see cref="T:IComparer{string}"/> over versioned strings such as X.YY.Z + /// <para/> + /// @lucene.internal + /// </summary> public static IComparer<string> VersionComparer { get @@ -139,30 +141,30 @@ namespace Lucene.Net.Util } /// <summary> - /// Returns <code>true</code> iff the ref starts with the given prefix. - /// Otherwise <code>false</code>. + /// Returns <c>true</c> if the <paramref name="ref"/> starts with the given <paramref name="prefix"/>. + /// Otherwise <c>false</c>. /// </summary> /// <param name="ref"> - /// the <seealso cref="BytesRef"/> to test </param> + /// The <see cref="BytesRef"/> to test. </param> /// <param name="prefix"> - /// the expected prefix </param> - /// <returns> Returns <code>true</code> iff the ref starts with the given prefix. - /// Otherwise <code>false</code>. </returns> + /// The expected prefix </param> + /// <returns> Returns <c>true</c> if the <paramref name="ref"/> starts with the given <paramref name="prefix"/>. + /// Otherwise <c>false</c>. </returns> public static bool StartsWith(BytesRef @ref, BytesRef prefix) { return SliceEquals(@ref, prefix, 0); } /// <summary> - /// Returns <code>true</code> iff the ref ends with the given suffix. Otherwise - /// <code>false</code>. + /// Returns <c>true</c> if the <paramref name="ref"/> ends with the given <paramref name="suffix"/>. Otherwise + /// <c>false</c>. /// </summary> /// <param name="ref"> - /// the <seealso cref="BytesRef"/> to test </param> + /// The <see cref="BytesRef"/> to test. </param> /// <param name="suffix"> - /// the expected suffix </param> - /// <returns> Returns <code>true</code> iff the ref ends with the given suffix. - /// Otherwise <code>false</code>. </returns> + /// The expected suffix </param> + /// <returns> Returns <c>true</c> if the <paramref name="ref"/> ends with the given <paramref name="suffix"/>. + /// Otherwise <c>false</c>. </returns> public static bool EndsWith(BytesRef @ref, BytesRef suffix) { return SliceEquals(@ref, suffix, @ref.Length - suffix.Length); @@ -190,7 +192,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Pass this as the seed to <seealso cref="#murmurhash3_x86_32"/>. </summary> + /// Pass this as the seed to <see cref="Murmurhash3_x86_32(byte[], int, int, int)"/>. </summary> // Poached from Guava: set a different salt/seed // for each JVM instance, to frustrate hash key collision @@ -238,7 +240,7 @@ namespace Lucene.Net.Util /// <summary> /// Returns the MurmurHash3_x86_32 hash. - /// Original source/tests at https://github.com/yonik/java_util/ + /// Original source/tests at <a href="https://github.com/yonik/java_util/";>https://github.com/yonik/java_util/</a>. /// </summary> public static int Murmurhash3_x86_32(byte[] data, int offset, int len, int seed) { @@ -296,6 +298,10 @@ namespace Lucene.Net.Util return h1; } + /// <summary> + /// Returns the MurmurHash3_x86_32 hash. + /// Original source/tests at <a href="https://github.com/yonik/java_util/";>https://github.com/yonik/java_util/</a>. + /// </summary> public static int Murmurhash3_x86_32(BytesRef bytes, int seed) { return Murmurhash3_x86_32(bytes.Bytes, bytes.Offset, bytes.Length, seed); http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/TimSorter.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/TimSorter.cs b/src/Lucene.Net/Util/TimSorter.cs index fd4eb55..680edc1 100644 --- a/src/Lucene.Net/Util/TimSorter.cs +++ b/src/Lucene.Net/Util/TimSorter.cs @@ -21,20 +21,22 @@ namespace Lucene.Net.Util */ /// <summary> - /// <seealso cref="Sorter"/> implementation based on the + /// <see cref="Sorter"/> implementation based on the /// <a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt";>TimSort</a> /// algorithm. - /// <p>this implementation is especially good at sorting partially-sorted + /// <para/>This implementation is especially good at sorting partially-sorted /// arrays and sorts small arrays with binary sort. - /// <p><b>NOTE</b>:There are a few differences with the original implementation:<ul> - /// <li><a name="maxTempSlots"/>The extra amount of memory to perform merges is - /// configurable. this allows small merges to be very fast while large merges - /// will be performed in-place (slightly slower). You can make sure that the - /// fast merge routine will always be used by having <code>maxTempSlots</code> - /// equal to half of the length of the slice of data to sort. - /// <li>Only the fast merge routine can gallop (the one that doesn't run - /// in-place) and it only gallops on the longest slice. - /// </ul> + /// <para/><b>NOTE</b>:There are a few differences with the original implementation: + /// <list type="bullet"> + /// <item><description><a name="maxTempSlots"/>The extra amount of memory to perform merges is + /// configurable. This allows small merges to be very fast while large merges + /// will be performed in-place (slightly slower). You can make sure that the + /// fast merge routine will always be used by having <c>maxTempSlots</c> + /// equal to half of the length of the slice of data to sort.</description></item> + /// <item><description>Only the fast merge routine can gallop (the one that doesn't run + /// in-place) and it only gallops on the longest slice.</description></item> + /// </list> + /// <para/> /// @lucene.internal /// </summary> public abstract class TimSorter : Sorter @@ -51,8 +53,8 @@ namespace Lucene.Net.Util internal int[] runEnds; /// <summary> - /// Create a new <seealso cref="TimSorter"/>. </summary> - /// <param name="maxTempSlots"> the <a href="#maxTempSlots">maximum amount of extra memory to run merges</a> </param> + /// Create a new <see cref="TimSorter"/>. </summary> + /// <param name="maxTempSlots"> The <a href="#maxTempSlots">maximum amount of extra memory to run merges</a> </param> protected TimSorter(int maxTempSlots) : base() { @@ -61,7 +63,7 @@ namespace Lucene.Net.Util } /// <summary> - /// Minimum run length for an array of length <code>length</code>. </summary> + /// Minimum run length for an array of length <paramref name="length"/>. </summary> internal static int MinRun(int length) { Debug.Assert(length >= MINRUN); @@ -106,7 +108,7 @@ namespace Lucene.Net.Util /// <summary> /// Compute the length of the next run, make the run sorted and return its - /// length. + /// length. /// </summary> internal virtual int NextRun() { @@ -227,6 +229,10 @@ namespace Lucene.Net.Util } } + /// <summary> + /// Sort the slice which starts at <paramref name="from"/> (inclusive) and ends at + /// <paramref name="to"/> (exclusive). + /// </summary> public override void Sort(int from, int to) { CheckRange(from, to); @@ -448,23 +454,23 @@ namespace Lucene.Net.Util } /// <summary> - /// Copy data from slot <code>src</code> to slot <code>dest</code>. </summary> + /// Copy data from slot <paramref name="src"/> to slot <paramref name="dest"/>>. </summary> protected abstract void Copy(int src, int dest); /// <summary> - /// Save all elements between slots <code>i</code> and <code>i+len</code> - /// into the temporary storage. + /// Save all elements between slots <paramref name="i"/> and <paramref name="i"/>+<paramref name="len"/> + /// into the temporary storage. /// </summary> protected abstract void Save(int i, int len); /// <summary> - /// Restore element <code>j</code> from the temporary storage into slot <code>i</code>. </summary> + /// Restore element <paramref name="j"/> from the temporary storage into slot <paramref name="i"/>. </summary> protected abstract void Restore(int i, int j); /// <summary> - /// Compare element <code>i</code> from the temporary storage with element - /// <code>j</code> from the slice to sort, similarly to - /// <seealso cref="#compare(int, int)"/>. + /// Compare element <paramref name="i"/> from the temporary storage with element + /// <paramref name="j"/> from the slice to sort, similarly to + /// <see cref="Sorter.Compare(int, int)"/>. /// </summary> protected abstract int CompareSaved(int i, int j); } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/ToStringUtils.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/ToStringUtils.cs b/src/Lucene.Net/Util/ToStringUtils.cs index af1e127..cab76c6 100644 --- a/src/Lucene.Net/Util/ToStringUtils.cs +++ b/src/Lucene.Net/Util/ToStringUtils.cs @@ -21,7 +21,7 @@ namespace Lucene.Net.Util */ /// <summary> - /// Helper methods to ease implementing <seealso cref="Object#toString()"/>. + /// Helper methods to ease implementing <see cref="object.ToString()"/>. /// </summary> public sealed class ToStringUtils { @@ -30,7 +30,7 @@ namespace Lucene.Net.Util } /// <summary> - /// for printing boost only if not 1.0 + /// For printing boost only if not 1.0. /// </summary> public static string Boost(float boost) { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/UnicodeUtil.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/UnicodeUtil.cs b/src/Lucene.Net/Util/UnicodeUtil.cs index 0e39d13..bfa7aa5 100644 --- a/src/Lucene.Net/Util/UnicodeUtil.cs +++ b/src/Lucene.Net/Util/UnicodeUtil.cs @@ -90,21 +90,19 @@ namespace Lucene.Net.Util */ /// <summary> - /// Class to encode java's UTF16 char[] into UTF8 byte[] - /// without always allocating a new byte[] as - /// String.getBytes(StandardCharsets.UTF_8) does. - /// + /// Class to encode .NET's UTF16 <see cref="T:char[]"/> into UTF8 <see cref="T:byte[]"/> + /// without always allocating a new <see cref="T:byte[]"/> as + /// <see cref="Encoding.GetBytes(string)"/> of <see cref="Encoding.UTF8"/> does. + /// <para/> /// @lucene.internal /// </summary> - public static class UnicodeUtil { /// <summary> /// A binary term consisting of a number of 0xff bytes, likely to be bigger than other terms - /// (e.g. collation keys) one would normally encounter, and definitely bigger than any UTF-8 terms. - /// <p> - /// WARNING: this is not a valid UTF8 Term - /// + /// (e.g. collation keys) one would normally encounter, and definitely bigger than any UTF-8 terms. + /// <para/> + /// WARNING: this is not a valid UTF8 Term /// </summary> public static readonly BytesRef BIG_TERM = new BytesRef(new byte[] { 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff }); // TODO this is unrelated here find a better place for it @@ -113,7 +111,6 @@ namespace Lucene.Net.Util public const int UNI_SUR_LOW_START = 0xDC00; public const int UNI_SUR_LOW_END = 0xDFFF; public const int UNI_REPLACEMENT_CHAR = 0xFFFD; - //private const int MIN_SUPPLEMENTARY_CODE_POINT = 0x10000; private const long UNI_MAX_BMP = 0x0000FFFF; @@ -123,8 +120,8 @@ namespace Lucene.Net.Util private const int SURROGATE_OFFSET = Character.MIN_SUPPLEMENTARY_CODE_POINT - (UNI_SUR_HIGH_START << (int)HALF_SHIFT) - UNI_SUR_LOW_START; /// <summary> - /// Encode characters from a char[] source, starting at - /// offset for length chars. After encoding, result.offset will always be 0. + /// Encode characters from a <see cref="T:char[]"/> <paramref name="source"/>, starting at + /// <paramref name="offset"/> for <paramref name="length"/> chars. After encoding, <c>result.Offset</c> will always be 0. /// </summary> // TODO: broken if incoming result.offset != 0 public static void UTF16toUTF8(char[] source, int offset, int length, BytesRef result) @@ -191,8 +188,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Encode characters from this <see cref="ICharSequence"/>, starting at offset - /// for length characters. After encoding, result.offset will always be 0. + /// Encode characters from this <see cref="ICharSequence"/>, starting at <paramref name="offset"/> + /// for <paramref name="length"/> characters. After encoding, <c>result.Offset</c> will always be 0. /// </summary> // TODO: broken if incoming result.offset != 0 public static void UTF16toUTF8(ICharSequence s, int offset, int length, BytesRef result) @@ -258,8 +255,9 @@ namespace Lucene.Net.Util } /// <summary> - /// Encode characters from this <see cref="string"/>, starting at offset - /// for length characters. After encoding, result.offset will always be 0. + /// Encode characters from this <see cref="string"/>, starting at <paramref name="offset"/> + /// for <paramref name="length"/> characters. After encoding, <c>result.Offset</c> will always be 0. + /// <para/> /// LUCENENET specific. /// </summary> // TODO: broken if incoming result.offset != 0 @@ -566,12 +564,12 @@ namespace Lucene.Net.Util /// <summary> /// Returns the number of code points in this UTF8 sequence. /// - /// <p>this method assumes valid UTF8 input. this method - /// <strong>does not perform</strong> full UTF8 validation, it will check only the + /// <para/>This method assumes valid UTF8 input. This method + /// <b>does not perform</b> full UTF8 validation, it will check only the /// first byte of each codepoint (for multi-byte sequences any bytes after /// the head are skipped). /// </summary> - /// <exception cref="IllegalArgumentException"> If invalid codepoint header byte occurs or the + /// <exception cref="ArgumentException"> If invalid codepoint header byte occurs or the /// content is prematurely truncated. </exception> public static int CodePointCount(BytesRef utf8) { @@ -603,12 +601,12 @@ namespace Lucene.Net.Util } /// <summary> - /// <p>this method assumes valid UTF8 input. this method - /// <strong>does not perform</strong> full UTF8 validation, it will check only the + /// This method assumes valid UTF8 input. This method + /// <b>does not perform</b> full UTF8 validation, it will check only the /// first byte of each codepoint (for multi-byte sequences any bytes after /// the head are skipped). /// </summary> - /// <exception cref="IllegalArgumentException"> If invalid codepoint header byte occurs or the + /// <exception cref="ArgumentException"> If invalid codepoint header byte occurs or the /// content is prematurely truncated. </exception> public static void UTF8toUTF32(BytesRef utf8, Int32sRef utf32) { @@ -674,30 +672,30 @@ namespace Lucene.Net.Util private const int TRAIL_SURROGATE_MASK_ = 0x3FF; /// <summary> - /// Trail surrogate minimum value </summary> + /// Trail surrogate minimum value. </summary> private const int TRAIL_SURROGATE_MIN_VALUE = 0xDC00; /// <summary> - /// Lead surrogate minimum value </summary> + /// Lead surrogate minimum value. </summary> private const int LEAD_SURROGATE_MIN_VALUE = 0xD800; /// <summary> - /// The minimum value for Supplementary code points </summary> + /// The minimum value for Supplementary code points. </summary> private const int SUPPLEMENTARY_MIN_VALUE = 0x10000; /// <summary> - /// Value that all lead surrogate starts with </summary> + /// Value that all lead surrogate starts with. </summary> private static readonly int LEAD_SURROGATE_OFFSET_ = LEAD_SURROGATE_MIN_VALUE - (SUPPLEMENTARY_MIN_VALUE >> LEAD_SURROGATE_SHIFT_); /// <summary> - /// Cover JDK 1.5 API. Create a String from an array of codePoints. + /// Cover JDK 1.5 API. Create a String from an array of <paramref name="codePoints"/>. /// </summary> - /// <param name="codePoints"> The code array </param> - /// <param name="offset"> The start of the text in the code point array </param> - /// <param name="count"> The number of code points </param> - /// <returns> a String representing the code points between offset and count </returns> - /// <exception cref="IllegalArgumentException"> If an invalid code point is encountered </exception> - /// <exception cref="IndexOutOfBoundsException"> If the offset or count are out of bounds. </exception> + /// <param name="codePoints"> The code array. </param> + /// <param name="offset"> The start of the text in the code point array. </param> + /// <param name="count"> The number of code points. </param> + /// <returns> a String representing the code points between offset and count. </returns> + /// <exception cref="ArgumentException"> If an invalid code point is encountered. </exception> + /// <exception cref="IndexOutOfRangeException"> If the offset or count are out of bounds. </exception> public static string NewString(int[] codePoints, int offset, int count) { char[] chars = ToCharArray(codePoints, offset, count); @@ -706,13 +704,13 @@ namespace Lucene.Net.Util /// <summary> /// Generates char array that represents the provided input code points. - /// + /// <para/> /// LUCENENET specific. /// </summary> - /// <param name="codePoints"> The code array </param> - /// <param name="offset"> The start of the text in the code point array </param> - /// <param name="count"> The number of code points </param> - /// <returns> a char array representing the code points between offset and count </returns> + /// <param name="codePoints"> The code array. </param> + /// <param name="offset"> The start of the text in the code point array. </param> + /// <param name="count"> The number of code points. </param> + /// <returns> a char array representing the code points between offset and count. </returns> // LUCENENET NOTE: This code was originally in the NewString() method (above). // It has been refactored from the original to remove the exception throw/catch and // instead proactively resizes the array instead of relying on excpetions + copy operations @@ -811,11 +809,11 @@ namespace Lucene.Net.Util } /// <summary> - /// Interprets the given byte array as UTF-8 and converts to UTF-16. The <seealso cref="CharsRef"/> will be extended if + /// Interprets the given byte array as UTF-8 and converts to UTF-16. The <see cref="CharsRef"/> will be extended if /// it doesn't provide enough space to hold the worst case of each byte becoming a UTF-16 codepoint. - /// <p> + /// <para/> /// NOTE: Full characters are read, even if this reads past the length passed (and - /// can result in an ArrayOutOfBoundsException if invalid UTF-8 is passed). + /// can result in an <see cref="IndexOutOfRangeException"/> if invalid UTF-8 is passed). /// Explicit checks for valid UTF-8 are not performed. /// </summary> // TODO: broken if chars.offset != 0 @@ -862,8 +860,8 @@ namespace Lucene.Net.Util } /// <summary> - /// Utility method for <seealso cref="#UTF8toUTF16(byte[], int, int, CharsRef)"/> </summary> - /// <seealso cref= #UTF8toUTF16(byte[], int, int, CharsRef) </seealso> + /// Utility method for <see cref="UTF8toUTF16(byte[], int, int, CharsRef)"/> </summary> + /// <seealso cref="UTF8toUTF16(byte[], int, int, CharsRef)"/> public static void UTF8toUTF16(BytesRef bytesRef, CharsRef chars) { UTF8toUTF16(bytesRef.Bytes, bytesRef.Offset, bytesRef.Length, chars); http://git-wip-us.apache.org/repos/asf/lucenenet/blob/268e78d4/src/Lucene.Net/Util/Version.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Util/Version.cs b/src/Lucene.Net/Util/Version.cs index 6a39cda..dc5b96c 100644 --- a/src/Lucene.Net/Util/Version.cs +++ b/src/Lucene.Net/Util/Version.cs @@ -25,10 +25,10 @@ namespace Lucene.Net.Util /// Use by certain classes to match version compatibility /// across releases of Lucene. /// - /// <p><b>WARNING</b>: When changing the version parameter + /// <para><b>WARNING</b>: When changing the version parameter /// that you supply to components in Lucene, do not simply /// change the version at search-time, but instead also adjust - /// your indexing code to match, and re-index.</p> + /// your indexing code to match, and re-index.</para> /// </summary> public enum LuceneVersion { @@ -124,16 +124,16 @@ namespace Lucene.Net.Util /// <summary> /// Match settings and bugs in Lucene's 4.8 release. - /// <p> - /// Use this to get the latest & greatest settings, bug - /// fixes, etc, for Lucene. + /// <para/> + /// Use this to get the latest & greatest settings, bug + /// fixes, etc, for Lucene. /// </summary> LUCENE_48, /* Add new constants for later versions **here** to respect order! */ /// <summary> - /// <p><b>WARNING</b>: if you use this setting, and then + /// <para/><b>WARNING</b>: if you use this setting, and then /// upgrade to a newer release of Lucene, sizable changes /// may happen. If backwards compatibility is important /// then you should instead explicitly specify an actual
