http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/TermRangeQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/TermRangeQuery.cs b/src/Lucene.Net/Search/TermRangeQuery.cs index 13c0998..87c7579 100644 --- a/src/Lucene.Net/Search/TermRangeQuery.cs +++ b/src/Lucene.Net/Search/TermRangeQuery.cs @@ -28,16 +28,17 @@ namespace Lucene.Net.Search using ToStringUtils = Lucene.Net.Util.ToStringUtils; /// <summary> - /// A Query that matches documents within an range of terms. + /// A <see cref="Query"/> that matches documents within an range of terms. /// - /// <p>this query matches the documents looking for terms that fall into the - /// supplied range according to {@link - /// Byte#compareTo(Byte)}. It is not intended - /// for numerical ranges; use <seealso cref="NumericRangeQuery"/> instead. + /// <para/>This query matches the documents looking for terms that fall into the + /// supplied range according to + /// <see cref="byte.CompareTo(byte)"/>. It is not intended + /// for numerical ranges; use <see cref="NumericRangeQuery"/> instead. /// - /// <p>this query uses the {@link - /// MultiTermQuery#CONSTANT_SCORE_AUTO_REWRITE_DEFAULT} + /// <para/>This query uses the + /// <see cref="MultiTermQuery.CONSTANT_SCORE_AUTO_REWRITE_DEFAULT"/> /// rewrite method. + /// <para/> /// @since 2.9 /// </summary> #if FEATURE_SERIALIZABLE @@ -51,25 +52,25 @@ namespace Lucene.Net.Search private bool includeUpper; /// <summary> - /// Constructs a query selecting all terms greater/equal than <code>lowerTerm</code> - /// but less/equal than <code>upperTerm</code>. + /// Constructs a query selecting all terms greater/equal than <paramref name="lowerTerm"/> + /// but less/equal than <paramref name="upperTerm"/>. /// - /// <p> - /// If an endpoint is null, it is said + /// <para/> + /// If an endpoint is <c>null</c>, it is said /// to be "open". Either or both endpoints may be open. Open endpoints may not /// be exclusive (you can't select all but the first or last term without /// explicitly specifying the term to exclude.) /// </summary> /// <param name="field"> The field that holds both lower and upper terms. </param> /// <param name="lowerTerm"> - /// The term text at the lower end of the range </param> + /// The term text at the lower end of the range. </param> /// <param name="upperTerm"> - /// The term text at the upper end of the range </param> + /// The term text at the upper end of the range. </param> /// <param name="includeLower"> - /// If true, the <code>lowerTerm</code> is + /// If true, the <paramref name="lowerTerm"/> is /// included in the range. </param> /// <param name="includeUpper"> - /// If true, the <code>upperTerm</code> is + /// If true, the <paramref name="upperTerm"/> is /// included in the range. </param> public TermRangeQuery(string field, BytesRef lowerTerm, BytesRef upperTerm, bool includeLower, bool includeUpper) : base(field) @@ -81,7 +82,7 @@ namespace Lucene.Net.Search } /// <summary> - /// Factory that creates a new TermRangeQuery using Strings for term text. + /// Factory that creates a new <see cref="TermRangeQuery"/> using <see cref="string"/>s for term text. /// </summary> public static TermRangeQuery NewStringRange(string field, string lowerTerm, string upperTerm, bool includeLower, bool includeUpper) { @@ -111,14 +112,14 @@ namespace Lucene.Net.Search } /// <summary> - /// Returns <code>true</code> if the lower endpoint is inclusive </summary> + /// Returns <c>true</c> if the lower endpoint is inclusive </summary> public virtual bool IncludesLower { get { return includeLower; } } /// <summary> - /// Returns <code>true</code> if the upper endpoint is inclusive </summary> + /// Returns <c>true</c> if the upper endpoint is inclusive </summary> public virtual bool IncludesUpper { get { return includeUpper; }
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/TermRangeTermsEnum.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/TermRangeTermsEnum.cs b/src/Lucene.Net/Search/TermRangeTermsEnum.cs index e33124b..f1b2381 100644 --- a/src/Lucene.Net/Search/TermRangeTermsEnum.cs +++ b/src/Lucene.Net/Search/TermRangeTermsEnum.cs @@ -25,11 +25,11 @@ namespace Lucene.Net.Search using TermsEnum = Lucene.Net.Index.TermsEnum; /// <summary> - /// Subclass of FilteredTermEnum for enumerating all terms that match the + /// Subclass of <see cref="FilteredTermsEnum"/> for enumerating all terms that match the /// specified range parameters. - /// <p>Term enumerations are always ordered by - /// <seealso cref="#getComparer"/>. Each term in the enumeration is - /// greater than all that precede it.</p> + /// <para>Term enumerations are always ordered by + /// <see cref="FilteredTermsEnum.Comparer"/>. Each term in the enumeration is + /// greater than all that precede it.</para> /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -43,10 +43,10 @@ namespace Lucene.Net.Search private readonly IComparer<BytesRef> termComp; /// <summary> - /// Enumerates all terms greater/equal than <code>lowerTerm</code> - /// but less/equal than <code>upperTerm</code>. + /// Enumerates all terms greater/equal than <paramref name="lowerTerm"/> + /// but less/equal than <paramref name="upperTerm"/>. /// - /// If an endpoint is null, it is said to be "open". Either or both + /// If an endpoint is <c>null</c>, it is said to be "open". Either or both /// endpoints may be open. Open endpoints may not be exclusive /// (you can't select all but the first or last term without /// explicitly specifying the term to exclude.) @@ -58,9 +58,9 @@ namespace Lucene.Net.Search /// <param name="upperTerm"> /// The term text at the upper end of the range </param> /// <param name="includeLower"> - /// If true, the <code>lowerTerm</code> is included in the range. </param> + /// If true, the <paramref name="lowerTerm"/> is included in the range. </param> /// <param name="includeUpper"> - /// If true, the <code>upperTerm</code> is included in the range. </param> + /// If true, the <paramref name="upperTerm"/> is included in the range. </param> public TermRangeTermsEnum(TermsEnum tenum, BytesRef lowerTerm, BytesRef upperTerm, bool includeLower, bool includeUpper) : base(tenum) { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/TermScorer.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/TermScorer.cs b/src/Lucene.Net/Search/TermScorer.cs index 4ddb81a..bf71c84 100644 --- a/src/Lucene.Net/Search/TermScorer.cs +++ b/src/Lucene.Net/Search/TermScorer.cs @@ -24,7 +24,7 @@ namespace Lucene.Net.Search using Similarity = Lucene.Net.Search.Similarities.Similarity; /// <summary> - /// Expert: A <code>Scorer</code> for documents matching a <code>Term</code>. + /// Expert: A <see cref="Scorer"/> for documents matching a <see cref="Index.Term"/>. /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -35,14 +35,14 @@ namespace Lucene.Net.Search private readonly Similarity.SimScorer docScorer; /// <summary> - /// Construct a <code>TermScorer</code>. + /// Construct a <see cref="TermScorer"/>. /// </summary> /// <param name="weight"> - /// The weight of the <code>Term</code> in the query. </param> + /// The weight of the <see cref="Index.Term"/> in the query. </param> /// <param name="td"> - /// An iterator over the documents matching the <code>Term</code>. </param> + /// An iterator over the documents matching the <see cref="Index.Term"/>. </param> /// <param name="docScorer"> - /// The </code>Similarity.SimScorer</code> implementation + /// The <see cref="Similarity.SimScorer"/> implementation /// to be used for score computations. </param> internal TermScorer(Weight weight, DocsEnum td, Similarity.SimScorer docScorer) : base(weight) @@ -62,9 +62,9 @@ namespace Lucene.Net.Search } /// <summary> - /// Advances to the next document matching the query. <br> + /// Advances to the next document matching the query. /// </summary> - /// <returns> the document matching the query or NO_MORE_DOCS if there are no more documents. </returns> + /// <returns> The document matching the query or <see cref="DocIdSetIterator.NO_MORE_DOCS"/> if there are no more documents. </returns> public override int NextDoc() { return docsEnum.NextDoc(); @@ -78,12 +78,13 @@ namespace Lucene.Net.Search /// <summary> /// Advances to the first match beyond the current whose document number is - /// greater than or equal to a given target. <br> - /// The implementation uses <seealso cref="docsEnum#advance(int)"/>. + /// greater than or equal to a given target. + /// <para/> + /// The implementation uses <see cref="DocIdSetIterator.Advance(int)"/>. /// </summary> /// <param name="target"> /// The target document number. </param> - /// <returns> the matching document or NO_MORE_DOCS if none exist. </returns> + /// <returns> The matching document or <see cref="DocIdSetIterator.NO_MORE_DOCS"/> if none exist. </returns> public override int Advance(int target) { return docsEnum.Advance(target); @@ -95,7 +96,7 @@ namespace Lucene.Net.Search } /// <summary> - /// Returns a string representation of this <code>TermScorer</code>. </summary> + /// Returns a string representation of this <see cref="TermScorer"/>. </summary> public override string ToString() { return "scorer(" + m_weight + ")"; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/TermStatistics.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/TermStatistics.cs b/src/Lucene.Net/Search/TermStatistics.cs index 55bb270..5bb162f 100644 --- a/src/Lucene.Net/Search/TermStatistics.cs +++ b/src/Lucene.Net/Search/TermStatistics.cs @@ -24,6 +24,7 @@ namespace Lucene.Net.Search /// <summary> /// Contains statistics for a specific term + /// <para/> /// @lucene.experimental /// </summary> #if FEATURE_SERIALIZABLE @@ -35,6 +36,9 @@ namespace Lucene.Net.Search private readonly long docFreq; private readonly long totalTermFreq; + /// <summary> + /// Sole constructor. + /// </summary> public TermStatistics(BytesRef term, long docFreq, long totalTermFreq) { Debug.Assert(docFreq >= 0); @@ -45,23 +49,23 @@ namespace Lucene.Net.Search } /// <summary> - /// returns the term text </summary> + /// Returns the term text </summary> public BytesRef Term { get { return term; } } /// <summary> - /// returns the number of documents this term occurs in </summary> - /// <seealso cref= TermsEnum#docFreq() </seealso> + /// Returns the number of documents this term occurs in </summary> + /// <seealso cref="Index.TermsEnum.DocFreq"/> public long DocFreq { get { return docFreq; } } /// <summary> - /// returns the total number of occurrences of this term </summary> - /// <seealso cref= TermsEnum#totalTermFreq() </seealso> + /// Returns the total number of occurrences of this term </summary> + /// <seealso cref="Index.TermsEnum.TotalTermFreq"/> public long TotalTermFreq { get { return totalTermFreq; } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/TimeLimitingCollector.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/TimeLimitingCollector.cs b/src/Lucene.Net/Search/TimeLimitingCollector.cs index 2bb2689..3ec1412 100644 --- a/src/Lucene.Net/Search/TimeLimitingCollector.cs +++ b/src/Lucene.Net/Search/TimeLimitingCollector.cs @@ -28,10 +28,10 @@ namespace Lucene.Net.Search using Counter = Lucene.Net.Util.Counter; /// <summary> - /// The <seealso cref="TimeLimitingCollector"/> is used to timeout search requests that + /// The <see cref="TimeLimitingCollector"/> is used to timeout search requests that /// take longer than the maximum allowed search time limit. After this time is /// exceeded, the search thread is stopped by throwing a - /// <seealso cref="TimeExceededException"/>. + /// <see cref="TimeExceededException"/>. /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -116,11 +116,11 @@ namespace Lucene.Net.Search private int docBase; /// <summary> - /// Create a TimeLimitedCollector wrapper over another <seealso cref="ICollector"/> with a specified timeout. </summary> - /// <param name="collector"> the wrapped <seealso cref="ICollector"/> </param> - /// <param name="clock"> the timer clock </param> - /// <param name="ticksAllowed"> max time allowed for collecting - /// hits after which <seealso cref="TimeExceededException"/> is thrown </param> + /// Create a <see cref="TimeLimitingCollector"/> wrapper over another <see cref="ICollector"/> with a specified timeout. </summary> + /// <param name="collector"> The wrapped <see cref="ICollector"/> </param> + /// <param name="clock"> The timer clock </param> + /// <param name="ticksAllowed"> Max time allowed for collecting + /// hits after which <see cref="TimeExceededException"/> is thrown </param> public TimeLimitingCollector(ICollector collector, Counter clock, long ticksAllowed) { this.collector = collector; @@ -133,18 +133,20 @@ namespace Lucene.Net.Search /// initialized once the first reader is passed to the collector. /// To include operations executed in prior to the actual document collection /// set the baseline through this method in your prelude. - /// <p> + /// <para> /// Example usage: - /// <pre class="prettyprint"> - /// Counter clock = ...; - /// long baseline = clock.get(); - /// // ... prepare search - /// TimeLimitingCollector collector = new TimeLimitingCollector(c, clock, numTicks); - /// collector.setBaseline(baseline); - /// indexSearcher.search(query, collector); - /// </pre> - /// </p> </summary> - /// <seealso cref= #setBaseline() </seealso> + /// <code> + /// // Counter is in the Lucene.Net.Util namespace + /// Counter clock = Counter.NewCounter(true); + /// long baseline = clock.Get(); + /// // ... prepare search + /// TimeLimitingCollector collector = new TimeLimitingCollector(c, clock, numTicks); + /// collector.SetBaseline(baseline); + /// indexSearcher.Search(query, collector); + /// </code> + /// </para> + /// </summary> + /// <seealso cref="SetBaseline()"/> public virtual void SetBaseline(long clockTime) { t0 = clockTime; @@ -152,7 +154,7 @@ namespace Lucene.Net.Search } /// <summary> - /// Syntactic sugar for <seealso cref="#setBaseline(long)"/> using <seealso cref="Counter#get()"/> + /// Syntactic sugar for <see cref="SetBaseline(long)"/> using <see cref="Counter.Get()"/> /// on the clock passed to the constructor. /// </summary> public virtual void SetBaseline() @@ -162,11 +164,11 @@ namespace Lucene.Net.Search /// <summary> /// Checks if this time limited collector is greedy in collecting the last hit. - /// A non greedy collector, upon a timeout, would throw a <seealso cref="TimeExceededException"/> + /// A non greedy collector, upon a timeout, would throw a <see cref="TimeExceededException"/> /// without allowing the wrapped collector to collect current doc. A greedy one would /// first allow the wrapped hit collector to collect current doc and only then - /// throw a <seealso cref="TimeExceededException"/>. </summary> - /// <seealso cref= #setGreedy(boolean) </seealso> + /// throw a <see cref="TimeExceededException"/>. + /// </summary> public virtual bool IsGreedy { get @@ -180,11 +182,11 @@ namespace Lucene.Net.Search } /// <summary> - /// Calls <seealso cref="ICollector#collect(int)"/> on the decorated <seealso cref="ICollector"/> + /// Calls <see cref="ICollector.Collect(int)"/> on the decorated <see cref="ICollector"/> /// unless the allowed time has passed, in which case it throws an exception. /// </summary> /// <exception cref="TimeExceededException"> - /// if the time allowed has exceeded. </exception> + /// If the time allowed has exceeded. </exception> public virtual void Collect(int doc) { long time = clock.Get(); @@ -223,26 +225,27 @@ namespace Lucene.Net.Search } /// <summary> - /// this is so the same timer can be used with a multi-phase search process such as grouping. - /// We don't want to create a new TimeLimitingCollector for each phase because that would + /// This is so the same timer can be used with a multi-phase search process such as grouping. + /// We don't want to create a new <see cref="TimeLimitingCollector"/> for each phase because that would /// reset the timer for each phase. Once time is up subsequent phases need to timeout quickly. /// </summary> - /// <param name="collector"> The actual collector performing search functionality </param> + /// <param name="collector"> The actual collector performing search functionality. </param> public virtual void SetCollector(ICollector collector) { this.collector = collector; } /// <summary> - /// Returns the global TimerThreads <seealso cref="Counter"/> - /// <p> - /// Invoking this creates may create a new instance of <seealso cref="TimerThread"/> iff - /// the global <seealso cref="TimerThread"/> has never been accessed before. The thread + /// Returns the global <see cref="TimerThread"/>'s <see cref="Counter"/> + /// <para> + /// Invoking this creates may create a new instance of <see cref="TimerThread"/> iff + /// the global <see cref="TimerThread"/> has never been accessed before. The thread /// returned from this method is started on creation and will be alive unless - /// you stop the <seealso cref="TimerThread"/> via <seealso cref="TimerThread#stopTimer()"/>. - /// </p> </summary> - /// <returns> the global TimerThreads <seealso cref="Counter"/> - /// @lucene.experimental </returns> + /// you stop the <see cref="TimerThread"/> via <see cref="TimerThread.StopTimer()"/>. + /// </para> + /// @lucene.experimental + /// </summary> + /// <returns> the global TimerThreads <seealso cref="Counter"/> </returns> public static Counter GlobalCounter { get @@ -252,16 +255,16 @@ namespace Lucene.Net.Search } /// <summary> - /// Returns the global <seealso cref="TimerThread"/>. - /// <p> - /// Invoking this creates may create a new instance of <seealso cref="TimerThread"/> iff - /// the global <seealso cref="TimerThread"/> has never been accessed before. The thread + /// Returns the global <see cref="TimerThread"/>. + /// <para> + /// Invoking this creates may create a new instance of <see cref="TimerThread"/> iff + /// the global <see cref="TimerThread"/> has never been accessed before. The thread /// returned from this method is started on creation and will be alive unless - /// you stop the <seealso cref="TimerThread"/> via <seealso cref="TimerThread#stopTimer()"/>. - /// </p> + /// you stop the <see cref="TimerThread"/> via <see cref="TimerThread.StopTimer()"/>. + /// </para> + /// @lucene.experimental /// </summary> - /// <returns> the global <seealso cref="TimerThread"/> - /// @lucene.experimental </returns> + /// <returns> the global <see cref="TimerThread"/> </returns> public static TimerThread GlobalTimerThread { get @@ -286,7 +289,8 @@ namespace Lucene.Net.Search /// <summary> /// Thread used to timeout search requests. - /// Can be stopped completely with <seealso cref="TimerThread#stopTimer()"/> + /// Can be stopped completely with <see cref="TimerThread.StopTimer()"/> + /// <para/> /// @lucene.experimental /// </summary> #if FEATURE_SERIALIZABLE @@ -368,7 +372,6 @@ namespace Lucene.Net.Search /// <summary> /// Return the timer resolution. </summary> - /// <seealso cref= #setResolution(long) </seealso> public long Resolution { get http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/TopDocs.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/TopDocs.cs b/src/Lucene.Net/Search/TopDocs.cs index c25123c..fec0de7 100644 --- a/src/Lucene.Net/Search/TopDocs.cs +++ b/src/Lucene.Net/Search/TopDocs.cs @@ -23,9 +23,9 @@ namespace Lucene.Net.Search */ /// <summary> - /// Represents hits returned by {@link - /// IndexSearcher#search(Query,Filter,int)} and {@link - /// IndexSearcher#search(Query,int)}. + /// Represents hits returned by + /// <see cref="IndexSearcher.Search(Query,Filter,int)"/> and + /// <see cref="IndexSearcher.Search(Query,int)"/>. /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -48,7 +48,7 @@ namespace Lucene.Net.Search /// <summary> /// Returns the maximum score value encountered. Note that in case - /// scores are not tracked, this returns <seealso cref="Float#NaN"/>. + /// scores are not tracked, this returns <see cref="float.NaN"/>. /// </summary> public virtual float MaxScore { @@ -63,7 +63,7 @@ namespace Lucene.Net.Search } /// <summary> - /// Constructs a TopDocs with a default maxScore=Float.NaN. </summary> + /// Constructs a <see cref="TopDocs"/> with a default <c>maxScore=System.Single.NaN</c>. </summary> internal TopDocs(int totalHits, ScoreDoc[] scoreDocs) : this(totalHits, scoreDocs, float.NaN) { @@ -250,16 +250,16 @@ namespace Lucene.Net.Search } /// <summary> - /// Returns a new TopDocs, containing topN results across - /// the provided TopDocs, sorting by the specified {@link - /// Sort}. Each of the TopDocs must have been sorted by - /// the same Sort, and sort field values must have been - /// filled (ie, <code>fillFields=true</code> must be - /// passed to {@link - /// TopFieldCollector#create}. - /// - /// <p>Pass sort=null to merge sort by score descending. + /// Returns a new <see cref="TopDocs"/>, containing <paramref name="topN"/> results across + /// the provided <see cref="TopDocs"/>, sorting by the specified + /// <see cref="Sort"/>. Each of the <see cref="TopDocs"/> must have been sorted by + /// the same <see cref="Sort"/>, and sort field values must have been + /// filled (ie, <c>fillFields=true</c> must be + /// passed to + /// <see cref="TopFieldCollector.Create(Sort, int, bool, bool, bool, bool)"/>. /// + /// <para/>Pass <paramref name="sort"/>=null to merge sort by score descending. + /// <para/> /// @lucene.experimental /// </summary> public static TopDocs Merge(Sort sort, int topN, TopDocs[] shardHits) @@ -268,8 +268,9 @@ namespace Lucene.Net.Search } /// <summary> - /// Same as <seealso cref="#merge(Sort, int, TopDocs[])"/> but also slices the result at the same time based - /// on the provided start and size. The return TopDocs will always have a scoreDocs with length of at most size. + /// Same as <see cref="Merge(Sort, int, TopDocs[])"/> but also slices the result at the same time based + /// on the provided start and size. The return <c>TopDocs</c> will always have a scoreDocs with length of + /// at most <see cref="Util.PriorityQueue{T}.Count"/>. /// </summary> public static TopDocs Merge(Sort sort, int start, int size, TopDocs[] shardHits) { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/TopDocsCollector.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/TopDocsCollector.cs b/src/Lucene.Net/Search/TopDocsCollector.cs index 211e2ef..cb8b956 100644 --- a/src/Lucene.Net/Search/TopDocsCollector.cs +++ b/src/Lucene.Net/Search/TopDocsCollector.cs @@ -22,15 +22,16 @@ namespace Lucene.Net.Search */ /// <summary> - /// A base class for all collectors that return a <seealso cref="TopDocs"/> output. this + /// A base class for all collectors that return a <see cref="TopDocs"/> output. This /// collector allows easy extension by providing a single constructor which - /// accepts a <seealso cref="PriorityQueue"/> as well as protected members for that - /// priority queue and a counter of the number of total hits.<br> + /// accepts a <see cref="Util.PriorityQueue{T}"/> as well as protected members for that + /// priority queue and a counter of the number of total hits. + /// <para/> /// Extending classes can override any of the methods to provide their own /// implementation, as well as avoid the use of the priority queue entirely by - /// passing null to <seealso cref="#TopDocsCollector(PriorityQueue)"/>. In that case + /// passing null to <see cref="TopDocsCollector(Util.PriorityQueue{T})"/>. In that case /// however, you might want to consider overriding all methods, in order to avoid - /// a NullPointerException. + /// a <see cref="NullReferenceException"/>. /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -38,15 +39,15 @@ namespace Lucene.Net.Search public abstract class TopDocsCollector<T> : ICollector, ITopDocsCollector where T : ScoreDoc { /// <summary> - /// this is used in case topDocs() is called with illegal parameters, or there - /// simply aren't (enough) results. + /// This is used in case <see cref="GetTopDocs()"/> is called with illegal parameters, or there + /// simply aren't (enough) results. /// </summary> protected static readonly TopDocs EMPTY_TOPDOCS = new TopDocs(0, new ScoreDoc[0], float.NaN); /// <summary> /// The priority queue which holds the top documents. Note that different - /// implementations of PriorityQueue give different meaning to 'top documents'. - /// HitQueue for example aggregates the top scoring documents, while other PQ + /// implementations of <see cref="PriorityQueue{T}"/> give different meaning to 'top documents'. + /// <see cref="HitQueue"/> for example aggregates the top scoring documents, while other priority queue /// implementations may hold documents sorted by other criteria. /// </summary> protected PriorityQueue<T> m_pq; @@ -55,14 +56,17 @@ namespace Lucene.Net.Search /// The total number of documents that the collector encountered. </summary> protected int m_totalHits; + /// <summary> + /// Sole constructor. + /// </summary> protected TopDocsCollector(PriorityQueue<T> pq) { this.m_pq = pq; } /// <summary> - /// Populates the results array with the ScoreDoc instances. this can be - /// overridden in case a different ScoreDoc type should be returned. + /// Populates the results array with the <see cref="ScoreDoc"/> instances. This can be + /// overridden in case a different <see cref="ScoreDoc"/> type should be returned. /// </summary> protected virtual void PopulateResults(ScoreDoc[] results, int howMany) { @@ -73,10 +77,10 @@ namespace Lucene.Net.Search } /// <summary> - /// Returns a <seealso cref="TopDocs"/> instance containing the given results. If - /// <code>results</code> is null it means there are no results to return, - /// either because there were 0 calls to collect() or because the arguments to - /// topDocs were invalid. + /// Returns a <see cref="TopDocs"/> instance containing the given results. If + /// <paramref name="results"/> is <c>null</c> it means there are no results to return, + /// either because there were 0 calls to <see cref="Collect(int)"/> or because the arguments to + /// <see cref="TopDocs"/> were invalid. /// </summary> protected virtual TopDocs NewTopDocs(ScoreDoc[] results, int start) { @@ -98,7 +102,7 @@ namespace Lucene.Net.Search } /// <summary> - /// The number of valid PQ entries + /// The number of valid priority queue entries /// </summary> protected virtual int TopDocsCount { @@ -122,44 +126,48 @@ namespace Lucene.Net.Search } /// <summary> - /// Returns the documents in the rage [start .. pq.size()) that were collected - /// by this collector. Note that if start >= pq.size(), an empty TopDocs is - /// returned.<br> - /// this method is convenient to call if the application always asks for the - /// last results, starting from the last 'page'.<br> + /// Returns the documents in the rage [<paramref name="start"/> .. pq.Count) that were collected + /// by this collector. Note that if <paramref name="start"/> >= pq.Count, an empty <see cref="TopDocs"/> is + /// returned. + /// <para/> + /// This method is convenient to call if the application always asks for the + /// last results, starting from the last 'page'. + /// <para/> /// <b>NOTE:</b> you cannot call this method more than once for each search /// execution. If you need to call it more than once, passing each time a - /// different <code>start</code>, you should call <seealso cref="#topDocs()"/> and work - /// with the returned <seealso cref="TopDocs"/> object, which will contain all the + /// different <paramref name="start"/>, you should call <see cref="GetTopDocs()"/> and work + /// with the returned <see cref="TopDocs"/> object, which will contain all the /// results this search execution collected. /// </summary> public virtual TopDocs GetTopDocs(int start) { // In case pq was populated with sentinel values, there might be less - // results than pq.size(). Therefore return all results until either - // pq.size() or totalHits. + // results than pq.Count. Therefore return all results until either + // pq.Count or totalHits. return GetTopDocs(start, TopDocsCount); } /// <summary> - /// Returns the documents in the rage [start .. start+howMany) that were - /// collected by this collector. Note that if start >= pq.size(), an empty - /// TopDocs is returned, and if pq.size() - start < howMany, then only the - /// available documents in [start .. pq.size()) are returned.<br> - /// this method is useful to call in case pagination of search results is + /// Returns the documents in the rage [<paramref name="start"/> .. <paramref name="start"/>+<paramref name="howMany"/>) that were + /// collected by this collector. Note that if <paramref name="start"/> >= pq.Count, an empty + /// <see cref="TopDocs"/> is returned, and if pq.Count - <paramref name="start"/> < <paramref name="howMany"/>, then only the + /// available documents in [<paramref name="start"/> .. pq.Count) are returned. + /// <para/> + /// This method is useful to call in case pagination of search results is /// allowed by the search application, as well as it attempts to optimize the - /// memory used by allocating only as much as requested by howMany.<br> + /// memory used by allocating only as much as requested by <paramref name="howMany"/>. + /// <para/> /// <b>NOTE:</b> you cannot call this method more than once for each search /// execution. If you need to call it more than once, passing each time a - /// different range, you should call <seealso cref="#topDocs()"/> and work with the - /// returned <seealso cref="TopDocs"/> object, which will contain all the results this + /// different range, you should call <see cref="GetTopDocs()"/> and work with the + /// returned <see cref="TopDocs"/> object, which will contain all the results this /// search execution collected. /// </summary> public virtual TopDocs GetTopDocs(int start, int howMany) { // In case pq was populated with sentinel values, there might be less - // results than pq.size(). Therefore return all results until either - // pq.size() or totalHits. + // results than pq.Count. Therefore return all results until either + // pq.Count or totalHits. int size = TopDocsCount; // Don't bother to throw an exception, just return an empty TopDocs in case @@ -197,7 +205,7 @@ namespace Lucene.Net.Search /// Called before successive calls to <see cref="Collect(int)"/>. Implementations /// that need the score of the current document (passed-in to /// <see cref="Collect(int)"/>), should save the passed-in <see cref="Scorer"/> and call - /// scorer.Score() when needed. + /// <see cref="Scorer.GetScore()"/> when needed. /// </summary> public abstract void SetScorer(Scorer scorer); @@ -219,11 +227,11 @@ namespace Lucene.Net.Search /// <summary> /// Called before collecting from each <see cref="AtomicReaderContext"/>. All doc ids in /// <see cref="Collect(int)"/> will correspond to <see cref="Index.IndexReaderContext.Reader"/>. - /// - /// Add <see cref="AtomicReaderContext#docBase"/> to the current <see cref="Index.IndexReaderContext.Reader"/>'s + /// <para/> + /// Add <see cref="AtomicReaderContext.DocBase"/> to the current <see cref="Index.IndexReaderContext.Reader"/>'s /// internal document id to re-base ids in <see cref="Collect(int)"/>. /// </summary> - /// <param name="context">next atomic reader context </param> + /// <param name="context">Next atomic reader context </param> public abstract void SetNextReader(AtomicReaderContext context); /// <summary> @@ -252,9 +260,46 @@ namespace Lucene.Net.Search public interface ITopDocsCollector : ICollector { // From TopDocsCollector<T> + /// <summary> + /// The total number of documents that matched this query. </summary> int TotalHits { get; } + + /// <summary> + /// Returns the top docs that were collected by this collector. </summary> TopDocs GetTopDocs(); + + /// <summary> + /// Returns the documents in the rage [<paramref name="start"/> .. pq.Count) that were collected + /// by this collector. Note that if <paramref name="start"/> >= pq.Count, an empty <see cref="TopDocs"/> is + /// returned. + /// <para/> + /// This method is convenient to call if the application always asks for the + /// last results, starting from the last 'page'. + /// <para/> + /// <b>NOTE:</b> you cannot call this method more than once for each search + /// execution. If you need to call it more than once, passing each time a + /// different <paramref name="start"/>, you should call <see cref="GetTopDocs()"/> and work + /// with the returned <see cref="TopDocs"/> object, which will contain all the + /// results this search execution collected. + /// </summary> TopDocs GetTopDocs(int start); + + /// <summary> + /// Returns the documents in the rage [<paramref name="start"/> .. <paramref name="start"/>+<paramref name="howMany"/>) that were + /// collected by this collector. Note that if <paramref name="start"/> >= pq.Count, an empty + /// <see cref="TopDocs"/> is returned, and if pq.Count - <paramref name="start"/> < <paramref name="howMany"/>, then only the + /// available documents in [<paramref name="start"/> .. pq.Count) are returned. + /// <para/> + /// This method is useful to call in case pagination of search results is + /// allowed by the search application, as well as it attempts to optimize the + /// memory used by allocating only as much as requested by <paramref name="howMany"/>. + /// <para/> + /// <b>NOTE:</b> you cannot call this method more than once for each search + /// execution. If you need to call it more than once, passing each time a + /// different range, you should call <see cref="GetTopDocs()"/> and work with the + /// returned <see cref="TopDocs"/> object, which will contain all the results this + /// search execution collected. + /// </summary> TopDocs GetTopDocs(int start, int howMany); } } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/TopFieldCollector.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/TopFieldCollector.cs b/src/Lucene.Net/Search/TopFieldCollector.cs index 9e07166..34911b0 100644 --- a/src/Lucene.Net/Search/TopFieldCollector.cs +++ b/src/Lucene.Net/Search/TopFieldCollector.cs @@ -24,12 +24,12 @@ namespace Lucene.Net.Search using Entry = Lucene.Net.Search.FieldValueHitQueue.Entry; /// <summary> - /// A <seealso cref="ICollector"/> that sorts by <seealso cref="SortField"/> using - /// <seealso cref="FieldComparer"/>s. - /// <p/> - /// See the <seealso cref="#create(Lucene.Net.Search.Sort, int, boolean, boolean, boolean, boolean)"/> method - /// for instantiating a TopFieldCollector. - /// + /// A <see cref="ICollector"/> that sorts by <see cref="SortField"/> using + /// <see cref="FieldComparer"/>s. + /// <para/> + /// See the <see cref="Create(Lucene.Net.Search.Sort, int, bool, bool, bool, bool)"/> method + /// for instantiating a <see cref="TopFieldCollector"/>. + /// <para/> /// @lucene.experimental /// </summary> #if FEATURE_SERIALIZABLE @@ -42,10 +42,10 @@ namespace Lucene.Net.Search // always compare lower than a real hit; this would // save having to check queueFull on each insert - /* - * Implements a TopFieldCollector over one SortField criteria, without - * tracking document scores and maxScore. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> over one <see cref="SortField"/> criteria, without + /// tracking document scores and maxScore. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -115,11 +115,11 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector over one SortField criteria, without - * tracking document scores and maxScore, and assumes out of orderness in doc - * Ids collection. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> over one <see cref="SortField"/> criteria, without + /// tracking document scores and maxScore, and assumes out of orderness in doc + /// Ids collection. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -167,10 +167,10 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector over one SortField criteria, while tracking - * document scores but no maxScore. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> over one <see cref="SortField"/> criteria, while tracking + /// document scores but no maxScore. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -235,11 +235,11 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector over one SortField criteria, while tracking - * document scores but no maxScore, and assumes out of orderness in doc Ids - * collection. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> over one <see cref="SortField"/> criteria, while tracking + /// document scores but no maxScore, and assumes out of orderness in doc Ids + /// collection. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -293,10 +293,10 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector over one SortField criteria, with tracking - * document scores and maxScore. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> over one <see cref="SortField"/> criteria, with tracking + /// document scores and maxScore. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -362,11 +362,11 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector over one SortField criteria, with tracking - * document scores and maxScore, and assumes out of orderness in doc Ids - * collection. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> over one <see cref="SortField"/> criteria, with tracking + /// document scores and maxScore, and assumes out of orderness in doc Ids + /// collection. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -419,10 +419,10 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector over multiple SortField criteria, without - * tracking document scores and maxScore. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> over multiple <see cref="SortField"/> criteria, without + /// tracking document scores and maxScore. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -527,11 +527,11 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector over multiple SortField criteria, without - * tracking document scores and maxScore, and assumes out of orderness in doc - * Ids collection. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> over multiple <see cref="SortField"/> criteria, without + /// tracking document scores and maxScore, and assumes out of orderness in doc + /// Ids collection. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -612,10 +612,10 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector over multiple SortField criteria, with - * tracking document scores and maxScore. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> over multiple <see cref="SortField"/> criteria, with + /// tracking document scores and maxScore. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -710,11 +710,11 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector over multiple SortField criteria, with - * tracking document scores and maxScore, and assumes out of orderness in doc - * Ids collection. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> over multiple <see cref="SortField"/> criteria, with + /// tracking document scores and maxScore, and assumes out of orderness in doc + /// Ids collection. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -800,10 +800,10 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector over multiple SortField criteria, with - * tracking document scores and maxScore. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> over multiple <see cref="SortField"/> criteria, with + /// tracking document scores and maxScore. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -896,11 +896,11 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector over multiple SortField criteria, with - * tracking document scores and maxScore, and assumes out of orderness in doc - * Ids collection. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> over multiple <see cref="SortField"/> criteria, with + /// tracking document scores and maxScore, and assumes out of orderness in doc + /// Ids collection. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -992,9 +992,9 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector when after != null. - */ + /// <summary> + /// Implements a <see cref="TopFieldCollector"/> when after != null. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -1218,82 +1218,82 @@ namespace Lucene.Net.Search } /// <summary> - /// Creates a new <seealso cref="TopFieldCollector"/> from the given + /// Creates a new <see cref="TopFieldCollector"/> from the given /// arguments. /// - /// <p><b>NOTE</b>: The instances returned by this method + /// <para/><b>NOTE</b>: The instances returned by this method /// pre-allocate a full array of length - /// <code>numHits</code>. + /// <paramref name="numHits"/>. /// </summary> /// <param name="sort"> - /// the sort criteria (SortFields). </param> + /// The sort criteria (<see cref="SortField"/>s). </param> /// <param name="numHits"> - /// the number of results to collect. </param> + /// The number of results to collect. </param> /// <param name="fillFields"> - /// specifies whether the actual field values should be returned on - /// the results (FieldDoc). </param> + /// Specifies whether the actual field values should be returned on + /// the results (<see cref="FieldDoc"/>). </param> /// <param name="trackDocScores"> - /// specifies whether document scores should be tracked and set on the - /// results. Note that if set to false, then the results' scores will - /// be set to Float.NaN. Setting this to true affects performance, as + /// Specifies whether document scores should be tracked and set on the + /// results. Note that if set to <c>false</c>, then the results' scores will + /// be set to <see cref="float.NaN"/>. Setting this to <c>true</c> affects performance, as /// it incurs the score computation on each competitive result. /// Therefore if document scores are not required by the application, - /// it is recommended to set it to false. </param> + /// it is recommended to set it to <c>false</c>. </param> /// <param name="trackMaxScore"> - /// specifies whether the query's maxScore should be tracked and set - /// on the resulting <seealso cref="TopDocs"/>. Note that if set to false, - /// <seealso cref="TopDocs#getMaxScore()"/> returns Float.NaN. Setting this to - /// true affects performance as it incurs the score computation on - /// each result. Also, setting this true automatically sets - /// <code>trackDocScores</code> to true as well. </param> + /// Specifies whether the query's <see cref="maxScore"/> should be tracked and set + /// on the resulting <see cref="TopDocs"/>. Note that if set to <c>false</c>, + /// <see cref="TopDocs.MaxScore"/> returns <see cref="float.NaN"/>. Setting this to + /// <c>true</c> affects performance as it incurs the score computation on + /// each result. Also, setting this <c>true</c> automatically sets + /// <paramref name="trackDocScores"/> to <c>true</c> as well. </param> /// <param name="docsScoredInOrder"> - /// specifies whether documents are scored in doc Id order or not by - /// the given <seealso cref="Scorer"/> in <seealso cref="#setScorer(Scorer)"/>. </param> - /// <returns> a <seealso cref="TopFieldCollector"/> instance which will sort the results by + /// Specifies whether documents are scored in doc Id order or not by + /// the given <see cref="Scorer"/> in <see cref="ICollector.SetScorer(Scorer)"/>. </param> + /// <returns> A <see cref="TopFieldCollector"/> instance which will sort the results by /// the sort criteria. </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> public static TopFieldCollector Create(Sort sort, int numHits, bool fillFields, bool trackDocScores, bool trackMaxScore, bool docsScoredInOrder) { return Create(sort, numHits, null, fillFields, trackDocScores, trackMaxScore, docsScoredInOrder); } /// <summary> - /// Creates a new <seealso cref="TopFieldCollector"/> from the given + /// Creates a new <see cref="TopFieldCollector"/> from the given /// arguments. /// - /// <p><b>NOTE</b>: The instances returned by this method + /// <para/><b>NOTE</b>: The instances returned by this method /// pre-allocate a full array of length - /// <code>numHits</code>. + /// <paramref name="numHits"/>. /// </summary> /// <param name="sort"> - /// the sort criteria (SortFields). </param> + /// The sort criteria (<see cref="SortField"/>s). </param> /// <param name="numHits"> - /// the number of results to collect. </param> + /// The number of results to collect. </param> /// <param name="after"> - /// only hits after this FieldDoc will be collected </param> + /// Only hits after this <see cref="FieldDoc"/> will be collected </param> /// <param name="fillFields"> - /// specifies whether the actual field values should be returned on - /// the results (FieldDoc). </param> + /// Specifies whether the actual field values should be returned on + /// the results (<see cref="FieldDoc"/>). </param> /// <param name="trackDocScores"> - /// specifies whether document scores should be tracked and set on the - /// results. Note that if set to false, then the results' scores will - /// be set to Float.NaN. Setting this to true affects performance, as + /// Specifies whether document scores should be tracked and set on the + /// results. Note that if set to <c>false</c>, then the results' scores will + /// be set to <see cref="float.NaN"/>. Setting this to <c>true</c> affects performance, as /// it incurs the score computation on each competitive result. /// Therefore if document scores are not required by the application, - /// it is recommended to set it to false. </param> + /// it is recommended to set it to <c>false</c>. </param> /// <param name="trackMaxScore"> - /// specifies whether the query's maxScore should be tracked and set - /// on the resulting <seealso cref="TopDocs"/>. Note that if set to false, - /// <seealso cref="TopDocs#getMaxScore()"/> returns Float.NaN. Setting this to - /// true affects performance as it incurs the score computation on - /// each result. Also, setting this true automatically sets - /// <code>trackDocScores</code> to true as well. </param> + /// Specifies whether the query's maxScore should be tracked and set + /// on the resulting <see cref="TopDocs"/>. Note that if set to <c>false</c>, + /// <see cref="TopDocs.MaxScore"/> returns <see cref="float.NaN"/>. Setting this to + /// <c>true</c> affects performance as it incurs the score computation on + /// each result. Also, setting this <c>true</c> automatically sets + /// <paramref name="trackDocScores"/> to <c>true</c> as well. </param> /// <param name="docsScoredInOrder"> - /// specifies whether documents are scored in doc Id order or not by - /// the given <seealso cref="Scorer"/> in <seealso cref="#setScorer(Scorer)"/>. </param> - /// <returns> a <seealso cref="TopFieldCollector"/> instance which will sort the results by + /// Specifies whether documents are scored in doc Id order or not by + /// the given <see cref="Scorer"/> in <see cref="ICollector.SetScorer(Scorer)"/>. </param> + /// <returns> A <see cref="TopFieldCollector"/> instance which will sort the results by /// the sort criteria. </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> public static TopFieldCollector Create(Sort sort, int numHits, FieldDoc after, bool fillFields, bool trackDocScores, bool trackMaxScore, bool docsScoredInOrder) { if (sort.fields.Length == 0) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/TopFieldDocs.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/TopFieldDocs.cs b/src/Lucene.Net/Search/TopFieldDocs.cs index b67a1c2..f0dcd68 100644 --- a/src/Lucene.Net/Search/TopFieldDocs.cs +++ b/src/Lucene.Net/Search/TopFieldDocs.cs @@ -22,8 +22,8 @@ namespace Lucene.Net.Search */ /// <summary> - /// Represents hits returned by {@link - /// IndexSearcher#search(Query,Filter,int,Sort)}. + /// Represents hits returned by + /// <see cref="IndexSearcher.Search(Query, Filter, int, Sort)"/>. /// </summary> #if FEATURE_SERIALIZABLE [Serializable] http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/TopScoreDocCollector.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/TopScoreDocCollector.cs b/src/Lucene.Net/Search/TopScoreDocCollector.cs index 683ca47..53ec973 100644 --- a/src/Lucene.Net/Search/TopScoreDocCollector.cs +++ b/src/Lucene.Net/Search/TopScoreDocCollector.cs @@ -23,15 +23,15 @@ namespace Lucene.Net.Search using AtomicReaderContext = Lucene.Net.Index.AtomicReaderContext; /// <summary> - /// A <seealso cref="ICollector"/> implementation that collects the top-scoring hits, - /// returning them as a <seealso cref="TopDocs"/>. this is used by <seealso cref="IndexSearcher"/> to - /// implement <seealso cref="TopDocs"/>-based search. Hits are sorted by score descending + /// A <see cref="ICollector"/> implementation that collects the top-scoring hits, + /// returning them as a <see cref="TopDocs"/>. this is used by <see cref="IndexSearcher"/> to + /// implement <see cref="TopDocs"/>-based search. Hits are sorted by score descending /// and then (when the scores are tied) docID ascending. When you create an /// instance of this collector you should know in advance whether documents are /// going to be collected in doc Id order or not. /// - /// <p><b>NOTE</b>: The values <seealso cref="Float#NaN"/> and - /// <seealso cref="Float#NEGATIVE_INFINITY"/> are not valid scores. this + /// <para/><b>NOTE</b>: The values <see cref="float.NaN"/> and + /// <see cref="float.NegativeInfinity"/> are not valid scores. This /// collector will not properly collect hits with such /// scores. /// </summary> @@ -261,13 +261,13 @@ namespace Lucene.Net.Search } /// <summary> - /// Creates a new <seealso cref="TopScoreDocCollector"/> given the number of hits to + /// Creates a new <see cref="TopScoreDocCollector"/> given the number of hits to /// collect and whether documents are scored in order by the input - /// <seealso cref="Scorer"/> to <seealso cref="#setScorer(Scorer)"/>. + /// <see cref="Scorer"/> to <see cref="SetScorer(Scorer)"/>. /// - /// <p><b>NOTE</b>: The instances returned by this method + /// <para/><b>NOTE</b>: The instances returned by this method /// pre-allocate a full array of length - /// <code>numHits</code>, and fill the array with sentinel + /// <paramref name="numHits"/>, and fill the array with sentinel /// objects. /// </summary> public static TopScoreDocCollector Create(int numHits, bool docsScoredInOrder) @@ -276,13 +276,13 @@ namespace Lucene.Net.Search } /// <summary> - /// Creates a new <seealso cref="TopScoreDocCollector"/> given the number of hits to + /// Creates a new <see cref="TopScoreDocCollector"/> given the number of hits to /// collect, the bottom of the previous page, and whether documents are scored in order by the input - /// <seealso cref="Scorer"/> to <seealso cref="#setScorer(Scorer)"/>. + /// <see cref="Scorer"/> to <see cref="SetScorer(Scorer)"/>. /// - /// <p><b>NOTE</b>: The instances returned by this method + /// <para/><b>NOTE</b>: The instances returned by this method /// pre-allocate a full array of length - /// <code>numHits</code>, and fill the array with sentinel + /// <paramref name="numHits"/>, and fill the array with sentinel /// objects. /// </summary> public static TopScoreDocCollector Create(int numHits, ScoreDoc after, bool docsScoredInOrder) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/TopTermsRewrite.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/TopTermsRewrite.cs b/src/Lucene.Net/Search/TopTermsRewrite.cs index 8f58ca5..dd5db58 100644 --- a/src/Lucene.Net/Search/TopTermsRewrite.cs +++ b/src/Lucene.Net/Search/TopTermsRewrite.cs @@ -31,10 +31,16 @@ namespace Lucene.Net.Search using TermsEnum = Lucene.Net.Index.TermsEnum; using TermState = Lucene.Net.Index.TermState; + internal interface ITopTermsRewrite + { + int Count { get; } // LUCENENET NOTE: This was size() in Lucene. + } + /// <summary> /// Base rewrite method for collecting only the top terms /// via a priority queue. - /// @lucene.internal Only public to be accessible by spans package. + /// <para/> + /// @lucene.internal - Only public to be accessible by spans package. /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -45,10 +51,10 @@ namespace Lucene.Net.Search private readonly int size; /// <summary> - /// Create a TopTermsBooleanQueryRewrite for + /// Create a <see cref="TopTermsRewrite{Q}"/> for /// at most <paramref name="count"/> terms. - /// <p> - /// NOTE: if <seealso cref="BooleanQuery#getMaxClauseCount"/> is smaller than + /// <para/> + /// NOTE: if <see cref="BooleanQuery.MaxClauseCount"/> is smaller than /// <paramref name="count"/>, then it will be used instead. /// </summary> public TopTermsRewrite(int count) @@ -57,7 +63,8 @@ namespace Lucene.Net.Search } /// <summary> - /// return the maximum priority queue size. + /// Return the maximum priority queue size. + /// <para/> /// NOTE: This was size() in Lucene. /// </summary> public virtual int Count @@ -69,7 +76,7 @@ namespace Lucene.Net.Search } /// <summary> - /// return the maximum size of the priority queue (for boolean rewrites this is BooleanQuery#getMaxClauseCount). </summary> + /// Return the maximum size of the priority queue (for boolean rewrites this is <see cref="BooleanQuery.MaxClauseCount"/>). </summary> protected abstract int MaxSize { get; } public override Query Rewrite(IndexReader reader, MultiTermQuery query) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/Weight.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Weight.cs b/src/Lucene.Net/Search/Weight.cs index 889f5ed..c977afd 100644 --- a/src/Lucene.Net/Search/Weight.cs +++ b/src/Lucene.Net/Search/Weight.cs @@ -24,32 +24,34 @@ namespace Lucene.Net.Search /// <summary> /// Expert: Calculate query weights and build query scorers. - /// <p> - /// The purpose of <seealso cref="Weight"/> is to ensure searching does not modify a - /// <seealso cref="Query"/>, so that a <seealso cref="Query"/> instance can be reused. <br> - /// <seealso cref="IndexSearcher"/> dependent state of the query should reside in the - /// <seealso cref="Weight"/>. <br> - /// <seealso cref="AtomicReader"/> dependent state should reside in the <seealso cref="Scorer"/>. - /// <p> - /// Since <seealso cref="Weight"/> creates <seealso cref="Scorer"/> instances for a given - /// <seealso cref="AtomicReaderContext"/> (<seealso cref="#scorer(AtomicReaderContext, Bits)"/>) + /// <para/> + /// The purpose of <see cref="Weight"/> is to ensure searching does not modify a + /// <see cref="Search.Query"/>, so that a <see cref="Search.Query"/> instance can be reused. + /// <para/> + /// <see cref="IndexSearcher"/> dependent state of the query should reside in the + /// <see cref="Weight"/>. + /// <para/> + /// <see cref="Index.AtomicReader"/> dependent state should reside in the <see cref="Scorer"/>. + /// <para/> + /// Since <see cref="Weight"/> creates <see cref="Scorer"/> instances for a given + /// <see cref="AtomicReaderContext"/> (<see cref="GetScorer(AtomicReaderContext, IBits)"/>) /// callers must maintain the relationship between the searcher's top-level - /// <seealso cref="IndexReaderContext"/> and the context used to create a <seealso cref="Scorer"/>. - /// <p> - /// A <code>Weight</code> is used in the following way: - /// <ol> - /// <li>A <code>Weight</code> is constructed by a top-level query, given a - /// <code>IndexSearcher</code> (<seealso cref="Query#createWeight(IndexSearcher)"/>). - /// <li>The <seealso cref="#getValueForNormalization()"/> method is called on the - /// <code>Weight</code> to compute the query normalization factor - /// <seealso cref="Similarity#queryNorm(float)"/> of the query clauses contained in the - /// query. - /// <li>The query normalization factor is passed to <seealso cref="#normalize(float, float)"/>. At - /// this point the weighting is complete. - /// <li>A <code>Scorer</code> is constructed by - /// <seealso cref="#scorer(AtomicReaderContext, Bits)"/>. - /// </ol> - /// + /// <see cref="Index.IndexReaderContext"/> and the context used to create a <see cref="Scorer"/>. + /// <para/> + /// A <see cref="Weight"/> is used in the following way: + /// <list type="number"> + /// <item><description>A <see cref="Weight"/> is constructed by a top-level query, given a + /// <see cref="IndexSearcher"/> (<see cref="Query.CreateWeight(IndexSearcher)"/>).</description></item> + /// <item><description>The <see cref="GetValueForNormalization()"/> method is called on the + /// <see cref="Weight"/> to compute the query normalization factor + /// <see cref="Similarities.Similarity.QueryNorm(float)"/> of the query clauses contained in the + /// query.</description></item> + /// <item><description>The query normalization factor is passed to <see cref="Normalize(float, float)"/>. At + /// this point the weighting is complete.</description></item> + /// <item><description>A <see cref="Scorer"/> is constructed by + /// <see cref="GetScorer(AtomicReaderContext, IBits)"/>.</description></item> + /// </list> + /// <para/> /// @since 2.9 /// </summary> #if FEATURE_SERIALIZABLE @@ -60,10 +62,10 @@ namespace Lucene.Net.Search /// <summary> /// An explanation of the score computation for the named document. /// </summary> - /// <param name="context"> the readers context to create the <seealso cref="Explanation"/> for. </param> - /// <param name="doc"> the document's id relative to the given context's reader </param> - /// <returns> an Explanation for the score </returns> - /// <exception cref="IOException"> if an <seealso cref="IOException"/> occurs </exception> + /// <param name="context"> The readers context to create the <see cref="Explanation"/> for. </param> + /// <param name="doc"> The document's id relative to the given context's reader </param> + /// <returns> An <see cref="Explanation"/> for the score </returns> + /// <exception cref="System.IO.IOException"> if an <see cref="System.IO.IOException"/> occurs </exception> public abstract Explanation Explain(AtomicReaderContext context, int doc); /// <summary> @@ -79,53 +81,54 @@ namespace Lucene.Net.Search public abstract void Normalize(float norm, float topLevelBoost); /// <summary> - /// Returns a <seealso cref="Scorer"/> which scores documents in/out-of order according - /// to <code>scoreDocsInOrder</code>. - /// <p> - /// <b>NOTE:</b> even if <code>scoreDocsInOrder</code> is false, it is - /// recommended to check whether the returned <code>Scorer</code> indeed scores - /// documents out of order (i.e., call <seealso cref="#scoresDocsOutOfOrder()"/>), as - /// some <code>Scorer</code> implementations will always return documents - /// in-order.<br> - /// <b>NOTE:</b> null can be returned if no documents will be scored by this + /// Returns a <see cref="Scorer"/> which scores documents in/out-of order according + /// to <c>scoreDocsInOrder</c>. + /// <para/> + /// <b>NOTE:</b> even if <c>scoreDocsInOrder</c> is <c>false</c>, it is + /// recommended to check whether the returned <see cref="Scorer"/> indeed scores + /// documents out of order (i.e., call <see cref="ScoresDocsOutOfOrder"/>), as + /// some <see cref="Scorer"/> implementations will always return documents + /// in-order. + /// <para/> + /// <b>NOTE:</b> <c>null</c> can be returned if no documents will be scored by this /// query. /// </summary> /// <param name="context"> - /// the <seealso cref="AtomicReaderContext"/> for which to return the <seealso cref="Scorer"/>. </param> + /// The <see cref="AtomicReaderContext"/> for which to return the <see cref="Scorer"/>. </param> /// <param name="acceptDocs"> - /// Bits that represent the allowable docs to match (typically deleted docs + /// <see cref="IBits"/> that represent the allowable docs to match (typically deleted docs /// but possibly filtering other documents) /// </param> - /// <returns> a <seealso cref="Scorer"/> which scores documents in/out-of order. </returns> - /// <exception cref="IOException"> if there is a low-level I/O error </exception> + /// <returns> A <see cref="Scorer"/> which scores documents in/out-of order. </returns> + /// <exception cref="System.IO.IOException"> if there is a low-level I/O error </exception> public abstract Scorer GetScorer(AtomicReaderContext context, IBits acceptDocs); /// <summary> - /// Optional method, to return a <seealso cref="BulkScorer"/> to - /// score the query and send hits to a <seealso cref="ICollector"/>. + /// Optional method, to return a <see cref="BulkScorer"/> to + /// score the query and send hits to a <see cref="ICollector"/>. /// Only queries that have a different top-level approach /// need to override this; the default implementation - /// pulls a normal <seealso cref="Scorer"/> and iterates and + /// pulls a normal <see cref="Scorer"/> and iterates and /// collects the resulting hits. /// </summary> /// <param name="context"> - /// the <seealso cref="AtomicReaderContext"/> for which to return the <seealso cref="Scorer"/>. </param> + /// The <see cref="AtomicReaderContext"/> for which to return the <see cref="Scorer"/>. </param> /// <param name="scoreDocsInOrder"> - /// specifies whether in-order scoring of documents is required. Note - /// that if set to false (i.e., out-of-order scoring is required), + /// Specifies whether in-order scoring of documents is required. Note + /// that if set to <c>false</c> (i.e., out-of-order scoring is required), /// this method can return whatever scoring mode it supports, as every /// in-order scorer is also an out-of-order one. However, an - /// out-of-order scorer may not support <seealso cref="Scorer#nextDoc()"/> - /// and/or <seealso cref="Scorer#advance(int)"/>, therefore it is recommended to + /// out-of-order scorer may not support <see cref="DocIdSetIterator.NextDoc()"/> + /// and/or <see cref="DocIdSetIterator.Advance(int)"/>, therefore it is recommended to /// request an in-order scorer if use of these /// methods is required. </param> /// <param name="acceptDocs"> - /// Bits that represent the allowable docs to match (typically deleted docs + /// <see cref="IBits"/> that represent the allowable docs to match (typically deleted docs /// but possibly filtering other documents) /// </param> - /// <returns> a <seealso cref="BulkScorer"/> which scores documents and + /// <returns> A <see cref="BulkScorer"/> which scores documents and /// passes them to a collector. </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> public virtual BulkScorer GetBulkScorer(AtomicReaderContext context, bool scoreDocsInOrder, IBits acceptDocs) { Scorer scorer = GetScorer(context, acceptDocs); @@ -141,7 +144,7 @@ namespace Lucene.Net.Search } /// <summary> - /// Just wraps a Scorer and performs top scoring using it. </summary> + /// Just wraps a <see cref="Scorer"/> and performs top scoring using it. </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -204,15 +207,15 @@ namespace Lucene.Net.Search } /// <summary> - /// Returns true iff this implementation scores docs only out of order. this - /// method is used in conjunction with <seealso cref="ICollector"/>'s - /// <seealso cref="ICollector#acceptsDocsOutOfOrder() acceptsDocsOutOfOrder"/> and - /// <seealso cref="#bulkScorer(AtomicReaderContext, boolean, Bits)"/> to - /// create a matching <seealso cref="Scorer"/> instance for a given <seealso cref="ICollector"/>, or + /// Returns true if this implementation scores docs only out of order. This + /// method is used in conjunction with <see cref="ICollector"/>'s + /// <see cref="ICollector.AcceptsDocsOutOfOrder"/> and + /// <see cref="GetBulkScorer(AtomicReaderContext, bool, IBits)"/> to + /// create a matching <see cref="Scorer"/> instance for a given <see cref="ICollector"/>, or /// vice versa. - /// <p> - /// <b>NOTE:</b> the default implementation returns <code>false</code>, i.e. - /// the <code>Scorer</code> scores documents in-order. + /// <para/> + /// <b>NOTE:</b> the default implementation returns <c>false</c>, i.e. + /// the <see cref="Scorer"/> scores documents in-order. /// </summary> public virtual bool ScoresDocsOutOfOrder { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/b2db5313/src/Lucene.Net/Search/WildcardQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/WildcardQuery.cs b/src/Lucene.Net/Search/WildcardQuery.cs index 52f0d12..4a76450 100644 --- a/src/Lucene.Net/Search/WildcardQuery.cs +++ b/src/Lucene.Net/Search/WildcardQuery.cs @@ -29,19 +29,19 @@ namespace Lucene.Net.Search using ToStringUtils = Lucene.Net.Util.ToStringUtils; /// <summary> - /// Implements the wildcard search query. Supported wildcards are <code>*</code>, which - /// matches any character sequence (including the empty one), and <code>?</code>, + /// Implements the wildcard search query. Supported wildcards are <c>*</c>, which + /// matches any character sequence (including the empty one), and <c>?</c>, /// which matches any single character. '\' is the escape character. - /// <p> + /// <para/> /// Note this query can be slow, as it /// needs to iterate over many terms. In order to prevent extremely slow WildcardQueries, - /// a Wildcard term should not start with the wildcard <code>*</code> + /// a Wildcard term should not start with the wildcard <c>*</c> /// - /// <p>this query uses the {@link - /// MultiTermQuery#CONSTANT_SCORE_AUTO_REWRITE_DEFAULT} + /// <para/>This query uses the + /// <see cref="MultiTermQuery.CONSTANT_SCORE_AUTO_REWRITE_DEFAULT"/> /// rewrite method. /// </summary> - /// <seealso cref= AutomatonQuery </seealso> + /// <seealso cref="AutomatonQuery"/> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -60,7 +60,7 @@ namespace Lucene.Net.Search public const char WILDCARD_ESCAPE = '\\'; /// <summary> - /// Constructs a query for terms matching <code>term</code>. + /// Constructs a query for terms matching <paramref name="term"/>. /// </summary> public WildcardQuery(Term term) : base(term, ToAutomaton(term)) @@ -69,6 +69,7 @@ namespace Lucene.Net.Search /// <summary> /// Convert Lucene wildcard syntax into an automaton. + /// <para/> /// @lucene.internal /// </summary> public static Automaton ToAutomaton(Term wildcardquery)
