You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucenenet.apache.org by ni...@apache.org on 2017/06/06 00:11:37 UTC
[04/48] lucenenet git commit: Lucene.Net.Search: Fixed up
documentation comments
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)