Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id E54F6200CAD for ; Tue, 6 Jun 2017 02:11:39 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id E3FB4160BF9; Tue, 6 Jun 2017 00:11:39 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 407E8160BE7 for ; Tue, 6 Jun 2017 02:11:37 +0200 (CEST) Received: (qmail 63946 invoked by uid 500); 6 Jun 2017 00:11:36 -0000 Mailing-List: contact commits-help@lucenenet.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: lucene-net-dev@lucenenet.apache.org Delivered-To: mailing list commits@lucenenet.apache.org Received: (qmail 63419 invoked by uid 99); 6 Jun 2017 00:11:34 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 06 Jun 2017 00:11:34 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id B1C92DFFAB; Tue, 6 Jun 2017 00:11:34 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: nightowl888@apache.org To: commits@lucenenet.apache.org Date: Tue, 06 Jun 2017 00:11:37 -0000 Message-Id: In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [04/48] lucenenet git commit: Lucene.Net.Search: Fixed up documentation comments archived-at: Tue, 06 Jun 2017 00:11:40 -0000 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; /// - /// A Query that matches documents within an range of terms. + /// A that matches documents within an range of terms. /// - ///

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 instead. + /// This query matches the documents looking for terms that fall into the + /// supplied range according to + /// . It is not intended + /// for numerical ranges; use instead. /// - ///

this query uses the {@link - /// MultiTermQuery#CONSTANT_SCORE_AUTO_REWRITE_DEFAULT} + /// This query uses the + /// /// rewrite method. + /// /// @since 2.9 ///

#if FEATURE_SERIALIZABLE @@ -51,25 +52,25 @@ namespace Lucene.Net.Search private bool includeUpper; /// - /// Constructs a query selecting all terms greater/equal than lowerTerm - /// but less/equal than upperTerm. + /// Constructs a query selecting all terms greater/equal than + /// but less/equal than . /// - ///

- /// If an endpoint is null, it is said + /// + /// If an endpoint is null, 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.) ///

/// The field that holds both lower and upper terms. /// - /// The term text at the lower end of the range + /// The term text at the lower end of the range. /// - /// The term text at the upper end of the range + /// The term text at the upper end of the range. /// - /// If true, the lowerTerm is + /// If true, the is /// included in the range. /// - /// If true, the upperTerm is + /// If true, the is /// included in the range. public TermRangeQuery(string field, BytesRef lowerTerm, BytesRef upperTerm, bool includeLower, bool includeUpper) : base(field) @@ -81,7 +82,7 @@ namespace Lucene.Net.Search } /// - /// Factory that creates a new TermRangeQuery using Strings for term text. + /// Factory that creates a new using s for term text. /// public static TermRangeQuery NewStringRange(string field, string lowerTerm, string upperTerm, bool includeLower, bool includeUpper) { @@ -111,14 +112,14 @@ namespace Lucene.Net.Search } /// - /// Returns true if the lower endpoint is inclusive + /// Returns true if the lower endpoint is inclusive public virtual bool IncludesLower { get { return includeLower; } } /// - /// Returns true if the upper endpoint is inclusive + /// Returns true if the upper endpoint is inclusive 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; /// - /// Subclass of FilteredTermEnum for enumerating all terms that match the + /// Subclass of for enumerating all terms that match the /// specified range parameters. - ///

Term enumerations are always ordered by - /// . Each term in the enumeration is - /// greater than all that precede it.

+ /// Term enumerations are always ordered by + /// . Each term in the enumeration is + /// greater than all that precede it. /// #if FEATURE_SERIALIZABLE [Serializable] @@ -43,10 +43,10 @@ namespace Lucene.Net.Search private readonly IComparer termComp; /// - /// Enumerates all terms greater/equal than lowerTerm - /// but less/equal than upperTerm. + /// Enumerates all terms greater/equal than + /// but less/equal than . /// - /// If an endpoint is null, it is said to be "open". Either or both + /// If an endpoint is null, 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 /// /// The term text at the upper end of the range /// - /// If true, the lowerTerm is included in the range. + /// If true, the is included in the range. /// - /// If true, the upperTerm is included in the range. + /// If true, the is included in the range. 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; /// - /// Expert: A Scorer for documents matching a Term. + /// Expert: A for documents matching a . /// #if FEATURE_SERIALIZABLE [Serializable] @@ -35,14 +35,14 @@ namespace Lucene.Net.Search private readonly Similarity.SimScorer docScorer; /// - /// Construct a TermScorer. + /// Construct a . /// /// - /// The weight of the Term in the query. + /// The weight of the in the query. /// - /// An iterator over the documents matching the Term. + /// An iterator over the documents matching the . /// - /// The Similarity.SimScorer implementation + /// The implementation /// to be used for score computations. internal TermScorer(Weight weight, DocsEnum td, Similarity.SimScorer docScorer) : base(weight) @@ -62,9 +62,9 @@ namespace Lucene.Net.Search } /// - /// Advances to the next document matching the query.
+ /// Advances to the next document matching the query. /// - /// the document matching the query or NO_MORE_DOCS if there are no more documents. + /// The document matching the query or if there are no more documents. public override int NextDoc() { return docsEnum.NextDoc(); @@ -78,12 +78,13 @@ namespace Lucene.Net.Search /// /// Advances to the first match beyond the current whose document number is - /// greater than or equal to a given target.
- /// The implementation uses . + /// greater than or equal to a given target. + /// + /// The implementation uses . /// /// /// The target document number. - /// the matching document or NO_MORE_DOCS if none exist. + /// The matching document or if none exist. public override int Advance(int target) { return docsEnum.Advance(target); @@ -95,7 +96,7 @@ namespace Lucene.Net.Search } /// - /// Returns a string representation of this TermScorer. + /// Returns a string representation of this . 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 /// /// Contains statistics for a specific term + /// /// @lucene.experimental /// #if FEATURE_SERIALIZABLE @@ -35,6 +36,9 @@ namespace Lucene.Net.Search private readonly long docFreq; private readonly long totalTermFreq; + /// + /// Sole constructor. + /// public TermStatistics(BytesRef term, long docFreq, long totalTermFreq) { Debug.Assert(docFreq >= 0); @@ -45,23 +49,23 @@ namespace Lucene.Net.Search } /// - /// returns the term text + /// Returns the term text public BytesRef Term { get { return term; } } /// - /// returns the number of documents this term occurs in - /// + /// Returns the number of documents this term occurs in + /// public long DocFreq { get { return docFreq; } } /// - /// returns the total number of occurrences of this term - /// + /// Returns the total number of occurrences of this term + /// 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; /// - /// The is used to timeout search requests that + /// The 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 - /// . + /// . /// #if FEATURE_SERIALIZABLE [Serializable] @@ -116,11 +116,11 @@ namespace Lucene.Net.Search private int docBase; /// - /// Create a TimeLimitedCollector wrapper over another with a specified timeout. - /// the wrapped - /// the timer clock - /// max time allowed for collecting - /// hits after which is thrown + /// Create a wrapper over another with a specified timeout. + /// The wrapped + /// The timer clock + /// Max time allowed for collecting + /// hits after which is thrown 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. - ///

+ /// /// Example usage: - /// 

-        ///   Counter clock = ...;
-        ///   long baseline = clock.get();
-        ///   // ... prepare search
-        ///   TimeLimitingCollector collector = new TimeLimitingCollector(c, clock, numTicks);
-        ///   collector.setBaseline(baseline);
-        ///   indexSearcher.search(query, collector);
-        ///
- ///

- /// + /// + /// // 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); + /// + /// + /// + /// public virtual void SetBaseline(long clockTime) { t0 = clockTime; @@ -152,7 +154,7 @@ namespace Lucene.Net.Search } /// - /// Syntactic sugar for using + /// Syntactic sugar for using /// on the clock passed to the constructor. /// public virtual void SetBaseline() @@ -162,11 +164,11 @@ namespace Lucene.Net.Search /// /// Checks if this time limited collector is greedy in collecting the last hit. - /// A non greedy collector, upon a timeout, would throw a + /// A non greedy collector, upon a timeout, would throw a /// 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 . - /// + /// throw a . + /// public virtual bool IsGreedy { get @@ -180,11 +182,11 @@ namespace Lucene.Net.Search } /// - /// Calls on the decorated + /// Calls on the decorated /// unless the allowed time has passed, in which case it throws an exception. /// /// - /// if the time allowed has exceeded. + /// If the time allowed has exceeded. public virtual void Collect(int doc) { long time = clock.Get(); @@ -223,26 +225,27 @@ namespace Lucene.Net.Search } /// - /// 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 for each phase because that would /// reset the timer for each phase. Once time is up subsequent phases need to timeout quickly. /// - /// The actual collector performing search functionality + /// The actual collector performing search functionality. public virtual void SetCollector(ICollector collector) { this.collector = collector; } /// - /// Returns the global TimerThreads - ///

- /// Invoking this creates may create a new instance of iff - /// the global has never been accessed before. The thread + /// Returns the global 's + /// + /// Invoking this creates may create a new instance of iff + /// the global has never been accessed before. The thread /// returned from this method is started on creation and will be alive unless - /// you stop the via . - ///

- /// the global TimerThreads - /// @lucene.experimental + /// you stop the via . + /// + /// @lucene.experimental + /// + /// the global TimerThreads public static Counter GlobalCounter { get @@ -252,16 +255,16 @@ namespace Lucene.Net.Search } /// - /// Returns the global . - ///

- /// Invoking this creates may create a new instance of iff - /// the global has never been accessed before. The thread + /// Returns the global . + /// + /// Invoking this creates may create a new instance of iff + /// the global has never been accessed before. The thread /// returned from this method is started on creation and will be alive unless - /// you stop the via . - ///

+ /// you stop the via . + /// + /// @lucene.experimental /// - /// the global - /// @lucene.experimental + /// the global public static TimerThread GlobalTimerThread { get @@ -286,7 +289,8 @@ namespace Lucene.Net.Search /// /// Thread used to timeout search requests. - /// Can be stopped completely with + /// Can be stopped completely with + /// /// @lucene.experimental /// #if FEATURE_SERIALIZABLE @@ -368,7 +372,6 @@ namespace Lucene.Net.Search /// /// Return the timer resolution. - /// 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 */ /// - /// Represents hits returned by {@link - /// IndexSearcher#search(Query,Filter,int)} and {@link - /// IndexSearcher#search(Query,int)}. + /// Represents hits returned by + /// and + /// . /// #if FEATURE_SERIALIZABLE [Serializable] @@ -48,7 +48,7 @@ namespace Lucene.Net.Search /// /// Returns the maximum score value encountered. Note that in case - /// scores are not tracked, this returns . + /// scores are not tracked, this returns . /// public virtual float MaxScore { @@ -63,7 +63,7 @@ namespace Lucene.Net.Search } /// - /// Constructs a TopDocs with a default maxScore=Float.NaN. + /// Constructs a with a default maxScore=System.Single.NaN. internal TopDocs(int totalHits, ScoreDoc[] scoreDocs) : this(totalHits, scoreDocs, float.NaN) { @@ -250,16 +250,16 @@ namespace Lucene.Net.Search } /// - /// 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, fillFields=true must be - /// passed to {@link - /// TopFieldCollector#create}. - /// - ///

Pass sort=null to merge sort by score descending. + /// Returns a new , containing results across + /// the provided , sorting by the specified + /// . Each of the must have been sorted by + /// the same , and sort field values must have been + /// filled (ie, fillFields=true must be + /// passed to + /// . /// + /// Pass =null to merge sort by score descending. + /// /// @lucene.experimental ///

public static TopDocs Merge(Sort sort, int topN, TopDocs[] shardHits) @@ -268,8 +268,9 @@ namespace Lucene.Net.Search } /// - /// Same as 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 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 . /// 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 */ /// - /// A base class for all collectors that return a output. this + /// A base class for all collectors that return a output. This /// collector allows easy extension by providing a single constructor which - /// accepts a as well as protected members for that - /// priority queue and a counter of the number of total hits.
+ /// accepts a as well as protected members for that + /// priority queue and a counter of the number of total hits. + /// /// 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 . In that case + /// passing null to . In that case /// however, you might want to consider overriding all methods, in order to avoid - /// a NullPointerException. + /// a . /// #if FEATURE_SERIALIZABLE [Serializable] @@ -38,15 +39,15 @@ namespace Lucene.Net.Search public abstract class TopDocsCollector : ICollector, ITopDocsCollector where T : ScoreDoc { /// - /// this is used in case topDocs() is called with illegal parameters, or there - /// simply aren't (enough) results. + /// This is used in case is called with illegal parameters, or there + /// simply aren't (enough) results. /// protected static readonly TopDocs EMPTY_TOPDOCS = new TopDocs(0, new ScoreDoc[0], float.NaN); /// /// 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 give different meaning to 'top documents'. + /// for example aggregates the top scoring documents, while other priority queue /// implementations may hold documents sorted by other criteria. /// protected PriorityQueue m_pq; @@ -55,14 +56,17 @@ namespace Lucene.Net.Search /// The total number of documents that the collector encountered. protected int m_totalHits; + /// + /// Sole constructor. + /// protected TopDocsCollector(PriorityQueue pq) { this.m_pq = pq; } /// - /// 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 instances. This can be + /// overridden in case a different type should be returned. /// protected virtual void PopulateResults(ScoreDoc[] results, int howMany) { @@ -73,10 +77,10 @@ namespace Lucene.Net.Search } /// - /// Returns a instance containing the given results. If - /// results 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 instance containing the given results. If + /// is null it means there are no results to return, + /// either because there were 0 calls to or because the arguments to + /// were invalid. /// protected virtual TopDocs NewTopDocs(ScoreDoc[] results, int start) { @@ -98,7 +102,7 @@ namespace Lucene.Net.Search } /// - /// The number of valid PQ entries + /// The number of valid priority queue entries /// protected virtual int TopDocsCount { @@ -122,44 +126,48 @@ namespace Lucene.Net.Search } /// - /// 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.
- /// this method is convenient to call if the application always asks for the - /// last results, starting from the last 'page'.
+ /// Returns the documents in the rage [ .. pq.Count) that were collected + /// by this collector. Note that if >= pq.Count, an empty is + /// returned. + /// + /// This method is convenient to call if the application always asks for the + /// last results, starting from the last 'page'. + /// /// NOTE: 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 start, you should call and work - /// with the returned object, which will contain all the + /// different , you should call and work + /// with the returned object, which will contain all the /// results this search execution collected. /// 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); } /// - /// 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.
- /// this method is useful to call in case pagination of search results is + /// Returns the documents in the rage [ .. +) that were + /// collected by this collector. Note that if >= pq.Count, an empty + /// is returned, and if pq.Count - < , then only the + /// available documents in [ .. pq.Count) are returned. + /// + /// 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.
+ /// memory used by allocating only as much as requested by . + /// /// NOTE: 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 and work with the - /// returned object, which will contain all the results this + /// different range, you should call and work with the + /// returned object, which will contain all the results this /// search execution collected. /// 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 . Implementations /// that need the score of the current document (passed-in to /// ), should save the passed-in and call - /// scorer.Score() when needed. + /// when needed. /// public abstract void SetScorer(Scorer scorer); @@ -219,11 +227,11 @@ namespace Lucene.Net.Search /// /// Called before collecting from each . All doc ids in /// will correspond to . - /// - /// Add to the current 's + /// + /// Add to the current 's /// internal document id to re-base ids in . /// - /// next atomic reader context + /// Next atomic reader context public abstract void SetNextReader(AtomicReaderContext context); /// @@ -252,9 +260,46 @@ namespace Lucene.Net.Search public interface ITopDocsCollector : ICollector { // From TopDocsCollector + /// + /// The total number of documents that matched this query. int TotalHits { get; } + + /// + /// Returns the top docs that were collected by this collector. TopDocs GetTopDocs(); + + /// + /// Returns the documents in the rage [ .. pq.Count) that were collected + /// by this collector. Note that if >= pq.Count, an empty is + /// returned. + /// + /// This method is convenient to call if the application always asks for the + /// last results, starting from the last 'page'. + /// + /// NOTE: 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 , you should call and work + /// with the returned object, which will contain all the + /// results this search execution collected. + /// TopDocs GetTopDocs(int start); + + /// + /// Returns the documents in the rage [ .. +) that were + /// collected by this collector. Note that if >= pq.Count, an empty + /// is returned, and if pq.Count - < , then only the + /// available documents in [ .. pq.Count) are returned. + /// + /// 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 . + /// + /// NOTE: 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 and work with the + /// returned object, which will contain all the results this + /// search execution collected. + /// 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; /// - /// A that sorts by using - /// s. - ///

- /// See the method - /// for instantiating a TopFieldCollector. - /// + /// A that sorts by using + /// s. + /// + /// See the method + /// for instantiating a . + /// /// @lucene.experimental ///

#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. - */ + /// + /// Implements a over one criteria, without + /// tracking document scores and maxScore. + /// #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. - */ + /// + /// Implements a over one criteria, without + /// tracking document scores and maxScore, and assumes out of orderness in doc + /// Ids collection. + /// #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. - */ + /// + /// Implements a over one criteria, while tracking + /// document scores but no maxScore. + /// #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. - */ + /// + /// Implements a over one criteria, while tracking + /// document scores but no maxScore, and assumes out of orderness in doc Ids + /// collection. + /// #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. - */ + /// + /// Implements a over one criteria, with tracking + /// document scores and maxScore. + /// #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. - */ + /// + /// Implements a over one criteria, with tracking + /// document scores and maxScore, and assumes out of orderness in doc Ids + /// collection. + /// #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. - */ + /// + /// Implements a over multiple criteria, without + /// tracking document scores and maxScore. + /// #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. - */ + /// + /// Implements a over multiple criteria, without + /// tracking document scores and maxScore, and assumes out of orderness in doc + /// Ids collection. + /// #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. - */ + /// + /// Implements a over multiple criteria, with + /// tracking document scores and maxScore. + /// #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. - */ + /// + /// Implements a over multiple criteria, with + /// tracking document scores and maxScore, and assumes out of orderness in doc + /// Ids collection. + /// #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. - */ + /// + /// Implements a over multiple criteria, with + /// tracking document scores and maxScore. + /// #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. - */ + /// + /// Implements a over multiple criteria, with + /// tracking document scores and maxScore, and assumes out of orderness in doc + /// Ids collection. + /// #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -992,9 +992,9 @@ namespace Lucene.Net.Search } } - /* - * Implements a TopFieldCollector when after != null. - */ + /// + /// Implements a when after != null. + /// #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -1218,82 +1218,82 @@ namespace Lucene.Net.Search } /// - /// Creates a new from the given + /// Creates a new from the given /// arguments. /// - ///

NOTE: The instances returned by this method + /// NOTE: The instances returned by this method /// pre-allocate a full array of length - /// numHits. + /// . ///

/// - /// the sort criteria (SortFields). + /// The sort criteria (s). /// - /// the number of results to collect. + /// The number of results to collect. /// - /// specifies whether the actual field values should be returned on - /// the results (FieldDoc). + /// Specifies whether the actual field values should be returned on + /// the results (). /// - /// 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 false, then the results' scores will + /// be set to . Setting this to true 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. + /// it is recommended to set it to false. /// - /// specifies whether the query's maxScore should be tracked and set - /// on the resulting . Note that if set to false, - /// returns Float.NaN. Setting this to - /// true affects performance as it incurs the score computation on - /// each result. Also, setting this true automatically sets - /// trackDocScores to true as well. + /// Specifies whether the query's should be tracked and set + /// on the resulting . Note that if set to false, + /// returns . Setting this to + /// true affects performance as it incurs the score computation on + /// each result. Also, setting this true automatically sets + /// to true as well. /// - /// specifies whether documents are scored in doc Id order or not by - /// the given in . - /// a instance which will sort the results by + /// Specifies whether documents are scored in doc Id order or not by + /// the given in . + /// A instance which will sort the results by /// the sort criteria. - /// if there is a low-level I/O error + /// If there is a low-level I/O error 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); } /// - /// Creates a new from the given + /// Creates a new from the given /// arguments. /// - ///

NOTE: The instances returned by this method + /// NOTE: The instances returned by this method /// pre-allocate a full array of length - /// numHits. + /// . ///

/// - /// the sort criteria (SortFields). + /// The sort criteria (s). /// - /// the number of results to collect. + /// The number of results to collect. /// - /// only hits after this FieldDoc will be collected + /// Only hits after this will be collected /// - /// specifies whether the actual field values should be returned on - /// the results (FieldDoc). + /// Specifies whether the actual field values should be returned on + /// the results (). /// - /// 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 false, then the results' scores will + /// be set to . Setting this to true 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. + /// it is recommended to set it to false. /// - /// specifies whether the query's maxScore should be tracked and set - /// on the resulting . Note that if set to false, - /// returns Float.NaN. Setting this to - /// true affects performance as it incurs the score computation on - /// each result. Also, setting this true automatically sets - /// trackDocScores to true as well. + /// Specifies whether the query's maxScore should be tracked and set + /// on the resulting . Note that if set to false, + /// returns . Setting this to + /// true affects performance as it incurs the score computation on + /// each result. Also, setting this true automatically sets + /// to true as well. /// - /// specifies whether documents are scored in doc Id order or not by - /// the given in . - /// a instance which will sort the results by + /// Specifies whether documents are scored in doc Id order or not by + /// the given in . + /// A instance which will sort the results by /// the sort criteria. - /// if there is a low-level I/O error + /// If there is a low-level I/O error 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 */ /// - /// Represents hits returned by {@link - /// IndexSearcher#search(Query,Filter,int,Sort)}. + /// Represents hits returned by + /// . /// #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; /// - /// A implementation that collects the top-scoring hits, - /// returning them as a . this is used by to - /// implement -based search. Hits are sorted by score descending + /// A implementation that collects the top-scoring hits, + /// returning them as a . this is used by to + /// implement -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. /// - ///

NOTE: The values and - /// are not valid scores. this + /// NOTE: The values and + /// are not valid scores. This /// collector will not properly collect hits with such /// scores. ///

@@ -261,13 +261,13 @@ namespace Lucene.Net.Search } /// - /// Creates a new given the number of hits to + /// Creates a new given the number of hits to /// collect and whether documents are scored in order by the input - /// to . + /// to . /// - ///

NOTE: The instances returned by this method + /// NOTE: The instances returned by this method /// pre-allocate a full array of length - /// numHits, and fill the array with sentinel + /// , and fill the array with sentinel /// objects. ///

public static TopScoreDocCollector Create(int numHits, bool docsScoredInOrder) @@ -276,13 +276,13 @@ namespace Lucene.Net.Search } /// - /// Creates a new given the number of hits to + /// Creates a new given the number of hits to /// collect, the bottom of the previous page, and whether documents are scored in order by the input - /// to . + /// to . /// - ///

NOTE: The instances returned by this method + /// NOTE: The instances returned by this method /// pre-allocate a full array of length - /// numHits, and fill the array with sentinel + /// , and fill the array with sentinel /// objects. ///

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. + } + /// /// Base rewrite method for collecting only the top terms /// via a priority queue. - /// @lucene.internal Only public to be accessible by spans package. + /// + /// @lucene.internal - Only public to be accessible by spans package. /// #if FEATURE_SERIALIZABLE [Serializable] @@ -45,10 +51,10 @@ namespace Lucene.Net.Search private readonly int size; /// - /// Create a TopTermsBooleanQueryRewrite for + /// Create a for /// at most terms. - ///

- /// NOTE: if is smaller than + /// + /// NOTE: if is smaller than /// , then it will be used instead. ///

public TopTermsRewrite(int count) @@ -57,7 +63,8 @@ namespace Lucene.Net.Search } /// - /// return the maximum priority queue size. + /// Return the maximum priority queue size. + /// /// NOTE: This was size() in Lucene. /// public virtual int Count @@ -69,7 +76,7 @@ namespace Lucene.Net.Search } /// - /// return the maximum size of the priority queue (for boolean rewrites this is BooleanQuery#getMaxClauseCount). + /// Return the maximum size of the priority queue (for boolean rewrites this is ). 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 /// /// Expert: Calculate query weights and build query scorers. - ///

- /// The purpose of is to ensure searching does not modify a - /// , so that a instance can be reused.
- /// dependent state of the query should reside in the - /// .
- /// dependent state should reside in the . - ///

- /// Since creates instances for a given - /// () + /// + /// The purpose of is to ensure searching does not modify a + /// , so that a instance can be reused. + /// + /// dependent state of the query should reside in the + /// . + /// + /// dependent state should reside in the . + /// + /// Since creates instances for a given + /// () /// callers must maintain the relationship between the searcher's top-level - /// and the context used to create a . - ///

- /// A Weight is used in the following way: - ///

    - ///
  1. A Weight is constructed by a top-level query, given a - /// IndexSearcher (). - ///
  2. The method is called on the - /// Weight to compute the query normalization factor - /// of the query clauses contained in the - /// query. - ///
  3. The query normalization factor is passed to . At - /// this point the weighting is complete. - ///
  4. A Scorer is constructed by - /// . - ///
- /// + /// and the context used to create a . + /// + /// A is used in the following way: + /// + /// A is constructed by a top-level query, given a + /// (). + /// The method is called on the + /// to compute the query normalization factor + /// of the query clauses contained in the + /// query. + /// The query normalization factor is passed to . At + /// this point the weighting is complete. + /// A is constructed by + /// . + /// + /// /// @since 2.9 /// #if FEATURE_SERIALIZABLE @@ -60,10 +62,10 @@ namespace Lucene.Net.Search /// /// An explanation of the score computation for the named document. /// - /// the readers context to create the for. - /// the document's id relative to the given context's reader - /// an Explanation for the score - /// if an occurs + /// The readers context to create the for. + /// The document's id relative to the given context's reader + /// An for the score + /// if an occurs public abstract Explanation Explain(AtomicReaderContext context, int doc); /// @@ -79,53 +81,54 @@ namespace Lucene.Net.Search public abstract void Normalize(float norm, float topLevelBoost); /// - /// Returns a which scores documents in/out-of order according - /// to scoreDocsInOrder. - ///

- /// NOTE: even if scoreDocsInOrder is false, it is - /// recommended to check whether the returned Scorer indeed scores - /// documents out of order (i.e., call ), as - /// some Scorer implementations will always return documents - /// in-order.
- /// NOTE: null can be returned if no documents will be scored by this + /// Returns a which scores documents in/out-of order according + /// to scoreDocsInOrder. + /// + /// NOTE: even if scoreDocsInOrder is false, it is + /// recommended to check whether the returned indeed scores + /// documents out of order (i.e., call ), as + /// some implementations will always return documents + /// in-order. + /// + /// NOTE: null can be returned if no documents will be scored by this /// query. ///

/// - /// the for which to return the . + /// The for which to return the . /// - /// Bits that represent the allowable docs to match (typically deleted docs + /// that represent the allowable docs to match (typically deleted docs /// but possibly filtering other documents) /// - /// a which scores documents in/out-of order. - /// if there is a low-level I/O error + /// A which scores documents in/out-of order. + /// if there is a low-level I/O error public abstract Scorer GetScorer(AtomicReaderContext context, IBits acceptDocs); /// - /// Optional method, to return a to - /// score the query and send hits to a . + /// Optional method, to return a to + /// score the query and send hits to a . /// Only queries that have a different top-level approach /// need to override this; the default implementation - /// pulls a normal and iterates and + /// pulls a normal and iterates and /// collects the resulting hits. /// /// - /// the for which to return the . + /// The for which to return the . /// - /// 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 false (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 - /// and/or , therefore it is recommended to + /// out-of-order scorer may not support + /// and/or , therefore it is recommended to /// request an in-order scorer if use of these /// methods is required. /// - /// Bits that represent the allowable docs to match (typically deleted docs + /// that represent the allowable docs to match (typically deleted docs /// but possibly filtering other documents) /// - /// a which scores documents and + /// A which scores documents and /// passes them to a collector. - /// if there is a low-level I/O error + /// if there is a low-level I/O error public virtual BulkScorer GetBulkScorer(AtomicReaderContext context, bool scoreDocsInOrder, IBits acceptDocs) { Scorer scorer = GetScorer(context, acceptDocs); @@ -141,7 +144,7 @@ namespace Lucene.Net.Search } /// - /// Just wraps a Scorer and performs top scoring using it. + /// Just wraps a and performs top scoring using it. #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -204,15 +207,15 @@ namespace Lucene.Net.Search } /// - /// Returns true iff this implementation scores docs only out of order. this - /// method is used in conjunction with 's - /// and - /// to - /// create a matching instance for a given , or + /// Returns true if this implementation scores docs only out of order. This + /// method is used in conjunction with 's + /// and + /// to + /// create a matching instance for a given , or /// vice versa. - ///

- /// NOTE: the default implementation returns false, i.e. - /// the Scorer scores documents in-order. + /// + /// NOTE: the default implementation returns false, i.e. + /// the scores documents in-order. ///

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; /// - /// Implements the wildcard search query. Supported wildcards are *, which - /// matches any character sequence (including the empty one), and ?, + /// Implements the wildcard search query. Supported wildcards are *, which + /// matches any character sequence (including the empty one), and ?, /// which matches any single character. '\' is the escape character. - ///

+ /// /// 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 * + /// a Wildcard term should not start with the wildcard * /// - ///

this query uses the {@link - /// MultiTermQuery#CONSTANT_SCORE_AUTO_REWRITE_DEFAULT} + /// This query uses the + /// /// rewrite method. ///

- /// + /// #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -60,7 +60,7 @@ namespace Lucene.Net.Search public const char WILDCARD_ESCAPE = '\\'; /// - /// Constructs a query for terms matching term. + /// Constructs a query for terms matching . /// public WildcardQuery(Term term) : base(term, ToAutomaton(term)) @@ -69,6 +69,7 @@ namespace Lucene.Net.Search /// /// Convert Lucene wildcard syntax into an automaton. + /// /// @lucene.internal /// public static Automaton ToAutomaton(Term wildcardquery)