Lucene.Net.Search.Spans: Fixed up documentation comments
Project: http://git-wip-us.apache.org/repos/asf/lucenenet/repo Commit: http://git-wip-us.apache.org/repos/asf/lucenenet/commit/396db51b Tree: http://git-wip-us.apache.org/repos/asf/lucenenet/tree/396db51b Diff: http://git-wip-us.apache.org/repos/asf/lucenenet/diff/396db51b Branch: refs/heads/master Commit: 396db51b964319e226feb5f519f039807f246c05 Parents: 2a1541c Author: Shad Storhaug <[email protected]> Authored: Sat Jun 3 03:28:13 2017 +0700 Committer: Shad Storhaug <[email protected]> Committed: Sat Jun 3 03:28:13 2017 +0700 ---------------------------------------------------------------------- CONTRIBUTING.md | 2 +- .../Search/Spans/FieldMaskingSpanQuery.cs | 48 +++++------ src/Lucene.Net/Search/Spans/NearSpansOrdered.cs | 87 +++++++++++++------- .../Search/Spans/NearSpansUnordered.cs | 18 ++-- src/Lucene.Net/Search/Spans/SpanFirstQuery.cs | 11 +-- .../Search/Spans/SpanMultiTermQueryWrapper.cs | 61 ++++++++------ .../Search/Spans/SpanNearPayloadCheckQuery.cs | 2 - src/Lucene.Net/Search/Spans/SpanNearQuery.cs | 17 ++-- src/Lucene.Net/Search/Spans/SpanNotQuery.cs | 26 +++--- src/Lucene.Net/Search/Spans/SpanOrQuery.cs | 4 +- .../Search/Spans/SpanPayloadCheckQuery.cs | 17 ++-- .../Search/Spans/SpanPositionCheckQuery.cs | 28 +++---- .../Search/Spans/SpanPositionRangeQuery.cs | 6 +- src/Lucene.Net/Search/Spans/SpanQuery.cs | 4 +- src/Lucene.Net/Search/Spans/SpanScorer.cs | 3 +- src/Lucene.Net/Search/Spans/SpanTermQuery.cs | 2 +- src/Lucene.Net/Search/Spans/Spans.cs | 57 +++++++------ 17 files changed, 210 insertions(+), 183 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/CONTRIBUTING.md ---------------------------------------------------------------------- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 68b0f1c..45f77ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,7 +52,7 @@ helpers to help with that, see for examples see our [Java style methods to avoid 1. Lucene.Net.Core (project) 1. Codecs (namespace) - 2. Search (namespace) (Except for Search.Payloads and Search.Similarities) + 2. Search (namespace) (Except for Search.Payloads, Search.Similarities, and Search.Spans) 3. Support (namespace) 4. Util (namespace) (Except for Util.Fst) 2. Lucene.Net.Codecs (project) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/FieldMaskingSpanQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/FieldMaskingSpanQuery.cs b/src/Lucene.Net/Search/Spans/FieldMaskingSpanQuery.cs index 0b73439..feb70ae 100644 --- a/src/Lucene.Net/Search/Spans/FieldMaskingSpanQuery.cs +++ b/src/Lucene.Net/Search/Spans/FieldMaskingSpanQuery.cs @@ -30,20 +30,20 @@ namespace Lucene.Net.Search.Spans using ToStringUtils = Lucene.Net.Util.ToStringUtils; /// <summary> - /// <p>Wrapper to allow <seealso cref="SpanQuery"/> objects participate in composite + /// <para>Wrapper to allow <see cref="SpanQuery"/> objects participate in composite /// single-field SpanQueries by 'lying' about their search field. That is, - /// the masked SpanQuery will function as normal, - /// but <seealso cref="SpanQuery#getField()"/> simply hands back the value supplied - /// in this class's constructor.</p> + /// the masked <see cref="SpanQuery"/> will function as normal, + /// but <see cref="SpanQuery.Field"/> simply hands back the value supplied + /// in this class's constructor.</para> /// - /// <p>this can be used to support Queries like <seealso cref="SpanNearQuery"/> or - /// <seealso cref="SpanOrQuery"/> across different fields, which is not ordinarily - /// permitted.</p> + /// <para>This can be used to support Queries like <see cref="SpanNearQuery"/> or + /// <see cref="SpanOrQuery"/> across different fields, which is not ordinarily + /// permitted.</para> /// - /// <p>this can be useful for denormalized relational data: for example, when - /// indexing a document with conceptually many 'children': </p> + /// <para>This can be useful for denormalized relational data: for example, when + /// indexing a document with conceptually many 'children': </para> /// - /// <pre> + /// <code> /// teacherid: 1 /// studentfirstname: james /// studentsurname: jones @@ -53,24 +53,24 @@ namespace Lucene.Net.Search.Spans /// studentsurname: smith /// studentfirstname: sally /// studentsurname: jones - /// </pre> + /// </code> /// - /// <p>a SpanNearQuery with a slop of 0 can be applied across two - /// <seealso cref="SpanTermQuery"/> objects as follows: - /// <pre class="prettyprint"> - /// SpanQuery q1 = new SpanTermQuery(new Term("studentfirstname", "james")); - /// SpanQuery q2 = new SpanTermQuery(new Term("studentsurname", "jones")); - /// SpanQuery q2m = new FieldMaskingSpanQuery(q2, "studentfirstname"); - /// Query q = new SpanNearQuery(new SpanQuery[]{q1, q2m}, -1, false); - /// </pre> + /// <para>A <see cref="SpanNearQuery"/> with a slop of 0 can be applied across two + /// <see cref="SpanTermQuery"/> objects as follows: + /// <code> + /// SpanQuery q1 = new SpanTermQuery(new Term("studentfirstname", "james")); + /// SpanQuery q2 = new SpanTermQuery(new Term("studentsurname", "jones")); + /// SpanQuery q2m = new FieldMaskingSpanQuery(q2, "studentfirstname"); + /// Query q = new SpanNearQuery(new SpanQuery[] { q1, q2m }, -1, false); + /// </code> /// to search for 'studentfirstname:james studentsurname:jones' and find /// teacherid 1 without matching teacherid 2 (which has a 'james' in position 0 - /// and 'jones' in position 1). </p> + /// and 'jones' in position 1). </para> /// - /// <p>Note: as <seealso cref="#getField()"/> returns the masked field, scoring will be - /// done using the Similarity and collection statistics of the field name supplied, - /// but with the term statistics of the real field. this may lead to exceptions, - /// poor performance, and unexpected scoring behaviour.</p> + /// <para>Note: as <see cref="Field"/> returns the masked field, scoring will be + /// done using the <see cref="Similarities.Similarity"/> and collection statistics of the field name supplied, + /// but with the term statistics of the real field. This may lead to exceptions, + /// poor performance, and unexpected scoring behavior.</para> /// </summary> #if FEATURE_SERIALIZABLE [Serializable] http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/NearSpansOrdered.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/NearSpansOrdered.cs b/src/Lucene.Net/Search/Spans/NearSpansOrdered.cs index 8af1196..9c606cb 100644 --- a/src/Lucene.Net/Search/Spans/NearSpansOrdered.cs +++ b/src/Lucene.Net/Search/Spans/NearSpansOrdered.cs @@ -31,25 +31,27 @@ namespace Lucene.Net.Search.Spans using TermContext = Lucene.Net.Index.TermContext; /// <summary> - /// A Spans that is formed from the ordered subspans of a SpanNearQuery + /// A <see cref="Spans"/> that is formed from the ordered subspans of a <see cref="SpanNearQuery"/> /// where the subspans do not overlap and have a maximum slop between them. - /// <p> - /// The formed spans only contains minimum slop matches.<br> + /// <para/> + /// The formed spans only contains minimum slop matches. + /// <para/> /// The matching slop is computed from the distance(s) between - /// the non overlapping matching Spans.<br> - /// Successive matches are always formed from the successive Spans - /// of the SpanNearQuery. - /// <p> + /// the non overlapping matching <see cref="Spans"/>. + /// <para/> + /// Successive matches are always formed from the successive <see cref="Spans"/> + /// of the <see cref="SpanNearQuery"/>. + /// <para/> /// The formed spans may contain overlaps when the slop is at least 1. /// For example, when querying using - /// <pre>t1 t2 t3</pre> + /// <c>t1 t2 t3</c> /// with slop at least 1, the fragment: - /// <pre>t1 t2 t1 t3 t2 t3</pre> + /// <c>t1 t2 t1 t3 t2 t3</c> /// matches twice: - /// <pre>t1 t2 .. t3 </pre> - /// <pre> t1 .. t2 t3</pre> - /// + /// <c>t1 t2 .. t3 </c> + /// <c> t1 .. t2 t3</c> /// + /// <para/> /// Expert: /// Only public for subclassing. Most implementations should not need this class /// </summary> @@ -63,11 +65,11 @@ namespace Lucene.Net.Search.Spans private bool more = false; /// <summary> - /// The spans in the same order as the SpanNearQuery </summary> + /// The spans in the same order as the <see cref="SpanNearQuery"/> </summary> private readonly Spans[] subSpans; /// <summary> - /// Indicates that all subSpans have same doc() </summary> + /// Indicates that all subSpans have same <see cref="Doc"/> </summary> private bool inSameDoc = false; private int matchDoc = -1; @@ -133,19 +135,22 @@ namespace Lucene.Net.Search.Spans query = spanNearQuery; // kept for toString() only. } - // inherit javadocs + /// <summary> + /// Returns the document number of the current match. Initially invalid. </summary> public override int Doc - // inherit javadocs { get { return matchDoc; } } + /// <summary> + /// Returns the start position of the current match. Initially invalid. </summary> public override int Start - // inherit javadocs { get { return matchStart; } } + /// <summary> + /// Returns the end position of the current match. Initially invalid. </summary> public override int End { get { return matchEnd; } @@ -184,7 +189,8 @@ namespace Lucene.Net.Search.Spans return minCost; } - // inherit javadocs + /// <summary> + /// Move to the next match, returning true iff any such exists. </summary> public override bool Next() { if (firstTime) @@ -207,7 +213,28 @@ namespace Lucene.Net.Search.Spans return AdvanceAfterOrdered(); } - // inherit javadocs + /// <summary> + /// Skips to the first match beyond the current, whose document number is + /// greater than or equal to <i>target</i>. + /// <para/>The behavior of this method is <b>undefined</b> when called with + /// <c> target <= current</c>, or after the iterator has exhausted. + /// Both cases may result in unpredicted behavior. + /// <para/>Returns <c>true</c> if there is such + /// a match. + /// <para/>Behaves as if written: + /// <code> + /// bool SkipTo(int target) + /// { + /// do + /// { + /// if (!Next()) + /// return false; + /// } while (target > Doc); + /// return true; + /// } + /// </code> + /// Most implementations are considerably more efficient than that. + /// </summary> public override bool SkipTo(int target) { if (firstTime) @@ -243,9 +270,9 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Advances the subSpans to just after an ordered match with a minimum slop - /// that is smaller than the slop allowed by the SpanNearQuery. </summary> - /// <returns> true iff there is such a match. </returns> + /// Advances the <see cref="SubSpans"/> to just after an ordered match with a minimum slop + /// that is smaller than the slop allowed by the <see cref="SpanNearQuery"/>. </summary> + /// <returns> <c>true</c> if there is such a match. </returns> private bool AdvanceAfterOrdered() { while (more && (inSameDoc || ToSameDoc())) @@ -259,7 +286,7 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Advance the subSpans to the same document </summary> + /// Advance the <see cref="SubSpans"/> to the same document </summary> private bool ToSameDoc() { sorter.Sort(0, subSpansByDoc.Length); @@ -288,10 +315,10 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Check whether two Spans in the same document are ordered. </summary> - /// <returns> true iff spans1 starts before spans2 + /// Check whether two <see cref="Spans"/> in the same document are ordered. </summary> + /// <returns> <c>true</c> if <paramref name="spans1"/> starts before <paramref name="spans2"/> /// or the spans start at the same position, - /// and spans1 ends before spans2. </returns> + /// and <paramref name="spans1"/> ends before <paramref name="spans2"/>. </returns> internal static bool DocSpansOrdered(Spans spans1, Spans spans2) { Debug.Assert(spans1.Doc == spans2.Doc, "doc1 " + spans1.Doc + " != doc2 " + spans2.Doc); @@ -302,7 +329,7 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Like <seealso cref="#docSpansOrdered(Spans,Spans)"/>, but use the spans + /// Like <see cref="DocSpansOrdered(Spans, Spans)"/>, but use the spans /// starts and ends as parameters. /// </summary> private static bool DocSpansOrdered(int start1, int end1, int start2, int end2) @@ -311,7 +338,7 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Order the subSpans within the same document by advancing all later spans + /// Order the <see cref="SubSpans"/> within the same document by advancing all later spans /// after the previous one. /// </summary> private bool StretchToOrder() @@ -338,9 +365,9 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// The subSpans are ordered in the same doc, so there is a possible match. + /// The <see cref="SubSpans"/> are ordered in the same doc, so there is a possible match. /// Compute the slop while making the match as short as possible by advancing - /// all subSpans except the last one in reverse order. + /// all <see cref="SubSpans"/> except the last one in reverse order. /// </summary> private bool ShrinkToAfterShortestMatch() { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/NearSpansUnordered.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/NearSpansUnordered.cs b/src/Lucene.Net/Search/Spans/NearSpansUnordered.cs index dc5959c..40c4d6c 100644 --- a/src/Lucene.Net/Search/Spans/NearSpansUnordered.cs +++ b/src/Lucene.Net/Search/Spans/NearSpansUnordered.cs @@ -28,8 +28,8 @@ namespace Lucene.Net.Search.Spans using TermContext = Lucene.Net.Index.TermContext; /// <summary> - /// Similar to <seealso cref="NearSpansOrdered"/>, but for the unordered case. - /// + /// Similar to <see cref="NearSpansOrdered"/>, but for the unordered case. + /// <para/> /// Expert: /// Only public for subclassing. Most implementations should not need this class /// </summary> @@ -82,7 +82,7 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Wraps a Spans, and can be used to form a linked list. </summary> + /// Wraps a <see cref="Spans"/>, and can be used to form a linked list. </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -142,8 +142,8 @@ namespace Lucene.Net.Search.Spans get { return spans.Start; } } - public override int End // TODO: Remove warning after API has been finalized + public override int End { get { return spans.End; } } @@ -309,17 +309,17 @@ namespace Lucene.Net.Search.Spans get { return Min.Start; } } - // TODO: Remove warning after API has been finalized - /// <summary> - /// WARNING: The List is not necessarily in order of the the positions </summary> - /// <returns> Collection of <code>byte[]</code> payloads </returns> - /// <exception cref="IOException"> if there is a low-level I/O error </exception> public override int End { get { return max.End; } } + // TODO: Remove warning after API has been finalized + /// <summary> + /// WARNING: The List is not necessarily in order of the the positions </summary> + /// <returns> Collection of <see cref="T:byte[]"/> payloads </returns> + /// <exception cref="System.IO.IOException"> if there is a low-level I/O error </exception> public override ICollection<byte[]> GetPayload() { var matchPayload = new HashSet<byte[]>(); http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/SpanFirstQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/SpanFirstQuery.cs b/src/Lucene.Net/Search/Spans/SpanFirstQuery.cs index 38bc9ad..6a7b402 100644 --- a/src/Lucene.Net/Search/Spans/SpanFirstQuery.cs +++ b/src/Lucene.Net/Search/Spans/SpanFirstQuery.cs @@ -26,12 +26,9 @@ namespace Lucene.Net.Search.Spans /// <summary> /// Matches spans near the beginning of a field. - /// <p/> - /// this class is a simple extension of <seealso cref="SpanPositionRangeQuery"/> in that it assumes the + /// <para/> + /// This class is a simple extension of <see cref="SpanPositionRangeQuery"/> in that it assumes the /// start to be zero and only checks the end boundary. - /// - /// - /// /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -39,8 +36,8 @@ namespace Lucene.Net.Search.Spans public class SpanFirstQuery : SpanPositionRangeQuery { /// <summary> - /// Construct a SpanFirstQuery matching spans in <code>match</code> whose end - /// position is less than or equal to <code>end</code>. + /// Construct a <see cref="SpanFirstQuery"/> matching spans in <paramref name="match"/> whose end + /// position is less than or equal to <paramref name="end"/>. /// </summary> public SpanFirstQuery(SpanQuery match, int end) : base(match, 0, end) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/SpanMultiTermQueryWrapper.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/SpanMultiTermQueryWrapper.cs b/src/Lucene.Net/Search/Spans/SpanMultiTermQueryWrapper.cs index ef4af40..f52ece5 100644 --- a/src/Lucene.Net/Search/Spans/SpanMultiTermQueryWrapper.cs +++ b/src/Lucene.Net/Search/Spans/SpanMultiTermQueryWrapper.cs @@ -28,20 +28,18 @@ namespace Lucene.Net.Search.Spans using TermContext = Lucene.Net.Index.TermContext; /// <summary> - /// Wraps any <seealso cref="MultiTermQuery"/> as a <seealso cref="SpanQuery"/>, - /// so it can be nested within other SpanQuery classes. - /// <p> - /// The query is rewritten by default to a <seealso cref="SpanOrQuery"/> containing + /// Wraps any <see cref="MultiTermQuery"/> as a <see cref="SpanQuery"/>, + /// so it can be nested within other <see cref="SpanQuery"/> classes. + /// <para/> + /// The query is rewritten by default to a <see cref="SpanOrQuery"/> containing /// the expanded terms, but this can be customized. - /// <p> + /// <para/> /// Example: - /// <blockquote><pre class="prettyprint"> - /// {@code + /// <code> /// WildcardQuery wildcard = new WildcardQuery(new Term("field", "bro?n")); - /// SpanQuery spanWildcard = new SpanMultiTermQueryWrapper<WildcardQuery>(wildcard); + /// SpanQuery spanWildcard = new SpanMultiTermQueryWrapper<WildcardQuery>(wildcard); /// // do something with spanWildcard, such as use it in a SpanFirstQuery - /// } - /// </pre></blockquote> + /// </code> /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -51,14 +49,14 @@ namespace Lucene.Net.Search.Spans protected readonly Q m_query; /// <summary> - /// Create a new SpanMultiTermQueryWrapper. + /// Create a new <see cref="SpanMultiTermQueryWrapper{Q}"/>. /// </summary> /// <param name="query"> Query to wrap. - /// <p> - /// NOTE: this will call <seealso cref="MultiTermQuery#setRewriteMethod(MultiTermQuery.RewriteMethod)"/> - /// on the wrapped <code>query</code>, changing its rewrite method to a suitable one for spans. + /// <para/> + /// NOTE: This will set <see cref="MultiTermQuery.MultiTermRewriteMethod"/> + /// on the wrapped <paramref name="query"/>, changing its rewrite method to a suitable one for spans. /// Be sure to not change the rewrite method on the wrapped query afterwards! Doing so will - /// throw <seealso cref="UnsupportedOperationException"/> on rewriting this query! </param> + /// throw <see cref="NotSupportedException"/> on rewriting this query! </param> public SpanMultiTermQueryWrapper(Q query) { this.m_query = query; @@ -76,7 +74,8 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Expert: returns the rewriteMethod + /// Expert: Gets or Sets the rewrite method. This only makes sense + /// to be a span rewrite method. /// </summary> public SpanRewriteMethod MultiTermRewriteMethod { @@ -176,11 +175,11 @@ namespace Lucene.Net.Search.Spans // LUCENENET NOTE: Moved SpanRewriteMethod outside of this class /// <summary> - /// A rewrite method that first translates each term into a SpanTermQuery in a - /// <seealso cref="Occur#SHOULD"/> clause in a BooleanQuery, and keeps the + /// A rewrite method that first translates each term into a <see cref="SpanTermQuery"/> in a + /// <see cref="Occur.SHOULD"/> clause in a <see cref="BooleanQuery"/>, and keeps the /// scores as computed by the query. /// </summary> - /// <seealso cref= #setRewriteMethod </seealso> + /// <seealso cref="MultiTermRewriteMethod"/> public static readonly SpanRewriteMethod SCORING_SPAN_QUERY_REWRITE = new SpanRewriteMethodAnonymousInnerClassHelper(); #if FEATURE_SERIALIZABLE @@ -231,15 +230,15 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// A rewrite method that first translates each term into a SpanTermQuery in a - /// <seealso cref="Occur#SHOULD"/> clause in a BooleanQuery, and keeps the + /// A rewrite method that first translates each term into a <see cref="SpanTermQuery"/> in a + /// <see cref="Occur.SHOULD"/> clause in a <see cref="BooleanQuery"/>, and keeps the /// scores as computed by the query. /// - /// <p> - /// this rewrite method only uses the top scoring terms so it will not overflow + /// <para/> + /// This rewrite method only uses the top scoring terms so it will not overflow /// the boolean max clause count. /// </summary> - /// <seealso cref= #setRewriteMethod </seealso> + /// <seealso cref="MultiTermRewriteMethod"/> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -248,8 +247,8 @@ namespace Lucene.Net.Search.Spans private readonly TopTermsRewrite<SpanOrQuery> @delegate; /// <summary> - /// Create a TopTermsSpanBooleanQueryRewrite for - /// at most <code>size</code> terms. + /// Create a <see cref="TopTermsSpanBooleanQueryRewrite"/> for + /// at most <paramref name="size"/> terms. /// </summary> public TopTermsSpanBooleanQueryRewrite(int size) { @@ -292,6 +291,7 @@ namespace Lucene.Net.Search.Spans /// <summary> /// return the maximum priority queue size. + /// <para/> /// NOTE: This was size() in Lucene. /// </summary> public int Count @@ -344,14 +344,21 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// LUCENENET specific interface for referring to/identifying a SpanMultipTermQueryWrapper without + /// LUCENENET specific interface for referring to/identifying a <see cref="Search.Spans.SpanMultiTermQueryWrapper{Q}"/> without /// referring to its generic closing type. /// </summary> public interface ISpanMultiTermQueryWrapper { + /// <summary> + /// Expert: Gets or Sets the rewrite method. This only makes sense + /// to be a span rewrite method. + /// </summary> SpanRewriteMethod MultiTermRewriteMethod { get; } Spans GetSpans(AtomicReaderContext context, IBits acceptDocs, IDictionary<Term, TermContext> termContexts); string Field { get; } + + /// <summary> + /// Returns the wrapped query </summary> Query WrappedQuery { get; } Query Rewrite(IndexReader reader); } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/SpanNearPayloadCheckQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/SpanNearPayloadCheckQuery.cs b/src/Lucene.Net/Search/Spans/SpanNearPayloadCheckQuery.cs index d00091f..b86e5d8 100644 --- a/src/Lucene.Net/Search/Spans/SpanNearPayloadCheckQuery.cs +++ b/src/Lucene.Net/Search/Spans/SpanNearPayloadCheckQuery.cs @@ -28,8 +28,6 @@ namespace Lucene.Net.Search.Spans /// <summary> /// Only return those matches that have a specific payload at /// the given position. - /// <p/> - /// /// </summary> #if FEATURE_SERIALIZABLE [Serializable] http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/SpanNearQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/SpanNearQuery.cs b/src/Lucene.Net/Search/Spans/SpanNearQuery.cs index 6c9a9e5..0ad2cb3 100644 --- a/src/Lucene.Net/Search/Spans/SpanNearQuery.cs +++ b/src/Lucene.Net/Search/Spans/SpanNearQuery.cs @@ -48,14 +48,13 @@ namespace Lucene.Net.Search.Spans private bool collectPayloads; /// <summary> - /// Construct a SpanNearQuery. Matches spans matching a span from each - /// clause, with up to <code>slop</code> total unmatched positions between - /// them. * When <code>inOrder</code> is true, the spans from each clause - /// must be * ordered as in <code>clauses</code>. </summary> - /// <param name="clauses"> the clauses to find near each other </param> + /// Construct a <see cref="SpanNearQuery"/>. Matches spans matching a span from each + /// clause, with up to <paramref name="slop"/> total unmatched positions between + /// them. * When <paramref name="inOrder"/> is <c>true</c>, the spans from each clause + /// must be * ordered as in <paramref name="clauses"/>. </summary> + /// <param name="clauses"> The clauses to find near each other </param> /// <param name="slop"> The slop value </param> - /// <param name="inOrder"> true if order is important - /// </param> + /// <param name="inOrder"> <c>true</c> if order is important</param> public SpanNearQuery(SpanQuery[] clauses, int slop, bool inOrder) : this(clauses, slop, inOrder, true) { @@ -101,7 +100,7 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Return true if matches are required to be in-order. </summary> + /// Return <c>true</c> if matches are required to be in-order. </summary> public virtual bool IsInOrder { get @@ -129,7 +128,7 @@ namespace Lucene.Net.Search.Spans public override string ToString(string field) { StringBuilder buffer = new StringBuilder(); - buffer.Append("spanNear(["); + buffer.Append("SpanNear(["); IEnumerator<SpanQuery> i = m_clauses.GetEnumerator(); bool isFirst = true; while (i.MoveNext()) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/SpanNotQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/SpanNotQuery.cs b/src/Lucene.Net/Search/Spans/SpanNotQuery.cs index 3d69c34..bb69f28 100644 --- a/src/Lucene.Net/Search/Spans/SpanNotQuery.cs +++ b/src/Lucene.Net/Search/Spans/SpanNotQuery.cs @@ -30,8 +30,8 @@ namespace Lucene.Net.Search.Spans using ToStringUtils = Lucene.Net.Util.ToStringUtils; /// <summary> - /// Removes matches which overlap with another SpanQuery or - /// within a x tokens before or y tokens after another SpanQuery. + /// Removes matches which overlap with another <see cref="SpanQuery"/> or + /// within a x tokens before or y tokens after another <see cref="SpanQuery"/>. /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -44,8 +44,8 @@ namespace Lucene.Net.Search.Spans private readonly int post; /// <summary> - /// Construct a SpanNotQuery matching spans from <code>include</code> which - /// have no overlap with spans from <code>exclude</code>. + /// Construct a <see cref="SpanNotQuery"/> matching spans from <paramref name="include"/> which + /// have no overlap with spans from <paramref name="exclude"/>. /// </summary> public SpanNotQuery(SpanQuery include, SpanQuery exclude) : this(include, exclude, 0, 0) @@ -53,9 +53,9 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Construct a SpanNotQuery matching spans from <code>include</code> which - /// have no overlap with spans from <code>exclude</code> within - /// <code>dist</code> tokens of <code>include</code>. + /// Construct a <see cref="SpanNotQuery"/> matching spans from <paramref name="include"/> which + /// have no overlap with spans from <paramref name="exclude"/> within + /// <paramref name="dist"/> tokens of <paramref name="include"/>. /// </summary> public SpanNotQuery(SpanQuery include, SpanQuery exclude, int dist) : this(include, exclude, dist, dist) @@ -63,9 +63,9 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Construct a SpanNotQuery matching spans from <code>include</code> which - /// have no overlap with spans from <code>exclude</code> within - /// <code>pre</code> tokens before or <code>post</code> tokens of <code>include</code>. + /// Construct a <see cref="SpanNotQuery"/> matching spans from <paramref name="include"/> which + /// have no overlap with spans from <paramref name="exclude"/> within + /// <paramref name="pre"/> tokens before or <paramref name="post"/> tokens of <paramref name="include"/>. /// </summary> public SpanNotQuery(SpanQuery include, SpanQuery exclude, int pre, int post) { @@ -81,7 +81,7 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Return the SpanQuery whose matches are filtered. </summary> + /// Return the <see cref="SpanQuery"/> whose matches are filtered. </summary> public virtual SpanQuery Include { get @@ -91,7 +91,7 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Return the SpanQuery whose matches must not overlap those returned. </summary> + /// Return the <see cref="SpanQuery"/> whose matches must not overlap those returned. </summary> public virtual SpanQuery Exclude { get @@ -306,7 +306,7 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Returns true iff <code>o</code> is equal to this. </summary> + /// Returns <c>true</c> if <paramref name="o"/> is equal to this. </summary> public override bool Equals(object o) { if (!base.Equals(o)) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/SpanOrQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/SpanOrQuery.cs b/src/Lucene.Net/Search/Spans/SpanOrQuery.cs index bfaecda..0d18490 100644 --- a/src/Lucene.Net/Search/Spans/SpanOrQuery.cs +++ b/src/Lucene.Net/Search/Spans/SpanOrQuery.cs @@ -41,7 +41,7 @@ namespace Lucene.Net.Search.Spans private string field; /// <summary> - /// Construct a SpanOrQuery merging the provided clauses. </summary> + /// Construct a <see cref="SpanOrQuery"/> merging the provided <paramref name="clauses"/>. </summary> public SpanOrQuery(params SpanQuery[] clauses) { // copy clauses array into an ArrayList @@ -53,7 +53,7 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Adds a clause to this query </summary> + /// Adds a <paramref name="clause"/> to this query </summary> public void AddClause(SpanQuery clause) { if (field == null) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/SpanPayloadCheckQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/SpanPayloadCheckQuery.cs b/src/Lucene.Net/Search/Spans/SpanPayloadCheckQuery.cs index 1dcb40b..0a68745 100644 --- a/src/Lucene.Net/Search/Spans/SpanPayloadCheckQuery.cs +++ b/src/Lucene.Net/Search/Spans/SpanPayloadCheckQuery.cs @@ -1,7 +1,6 @@ using Lucene.Net.Support; using System.Collections.Generic; using System; -using System.Linq; using System.Text; namespace Lucene.Net.Search.Spans @@ -26,14 +25,12 @@ namespace Lucene.Net.Search.Spans using ToStringUtils = Lucene.Net.Util.ToStringUtils; /// <summary> - /// Only return those matches that have a specific payload at - /// the given position. - /// <p/> - /// Do not use this with an SpanQuery that contains a <seealso cref="Lucene.Net.Search.Spans.SpanNearQuery"/>. Instead, use - /// <seealso cref="SpanNearPayloadCheckQuery"/> since it properly handles the fact that payloads - /// aren't ordered by <seealso cref="Lucene.Net.Search.Spans.SpanNearQuery"/>. - /// - /// + /// Only return those matches that have a specific payload at + /// the given position. + /// <para/> + /// Do not use this with a <see cref="SpanQuery"/> that contains a <see cref="Lucene.Net.Search.Spans.SpanNearQuery"/>. Instead, use + /// <see cref="SpanNearPayloadCheckQuery"/> since it properly handles the fact that payloads + /// aren't ordered by <see cref="Lucene.Net.Search.Spans.SpanNearQuery"/>. /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -44,7 +41,7 @@ namespace Lucene.Net.Search.Spans /// /// <param name="match"> The underlying <see cref="SpanQuery"/> to check </param> - /// <param name="payloadToMatch"> The <see cref="T:ICollection<byte[]>"/> of payloads to match. + /// <param name="payloadToMatch"> The <see cref="T:ICollection{byte[]}"/> of payloads to match. /// IMPORTANT: If the type provided does not implement <see cref="IList{T}"/> (including arrays), /// <see cref="ISet{T}"/>, or <see cref="IDictionary{TKey, TValue}"/>, it should provide an /// <see cref="object.Equals(object)"/> and <see cref="object.GetHashCode()"/> implementation http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/SpanPositionCheckQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/SpanPositionCheckQuery.cs b/src/Lucene.Net/Search/Spans/SpanPositionCheckQuery.cs index 492cbdb..ec66553 100644 --- a/src/Lucene.Net/Search/Spans/SpanPositionCheckQuery.cs +++ b/src/Lucene.Net/Search/Spans/SpanPositionCheckQuery.cs @@ -27,8 +27,7 @@ namespace Lucene.Net.Search.Spans using TermContext = Lucene.Net.Index.TermContext; /// <summary> - /// Base class for filtering a SpanQuery based on the position of a match. - /// + /// Base class for filtering a <see cref="SpanQuery"/> based on the position of a match. /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -42,9 +41,9 @@ namespace Lucene.Net.Search.Spans this.m_match = match; } - /// <returns> the SpanQuery whose matches are filtered. - /// - /// </returns> + /// <returns> + /// The <see cref="SpanQuery"/> whose matches are filtered. + /// </returns> public virtual SpanQuery Match { get @@ -67,7 +66,7 @@ namespace Lucene.Net.Search.Spans } /// <summary> - /// Return value for <seealso cref="SpanPositionCheckQuery#acceptPosition(Spans)"/>. + /// Return value for <see cref="SpanPositionCheckQuery.AcceptPosition(Spans)"/>. /// </summary> protected internal enum AcceptStatus { @@ -88,17 +87,15 @@ namespace Lucene.Net.Search.Spans /// <summary> /// Implementing classes are required to return whether the current position is a match for the passed in - /// "match" <seealso cref="Lucene.Net.Search.Spans.SpanQuery"/>. - /// - /// this is only called if the underlying <seealso cref="Lucene.Net.Search.Spans.Spans#next()"/> for the + /// "match" <see cref="Lucene.Net.Search.Spans.SpanQuery"/>. + /// <para/> + /// This is only called if the underlying <see cref="Lucene.Net.Search.Spans.Spans.Next()"/> for the /// match is successful - /// /// </summary> - /// <param name="spans"> The <seealso cref="Lucene.Net.Search.Spans.Spans"/> instance, positioned at the spot to check </param> - /// <returns> whether the match is accepted, rejected, or rejected and should move to the next doc. + /// <param name="spans"> The <see cref="Lucene.Net.Search.Spans.Spans"/> instance, positioned at the spot to check </param> + /// <returns> Whether the match is accepted, rejected, or rejected and should move to the next doc. /// </returns> - /// <seealso cref= Lucene.Net.Search.Spans.Spans#next() - /// </seealso> + /// <seealso cref="Lucene.Net.Search.Spans.Spans.Next()"/> protected abstract AcceptStatus AcceptPosition(Spans spans); public override Spans GetSpans(AtomicReaderContext context, IBits acceptDocs, IDictionary<Term, TermContext> termContexts) @@ -198,8 +195,8 @@ namespace Lucene.Net.Search.Spans get { return spans.Start; } } - public override int End // TODO: Remove warning after API has been finalized + public override int End { get { return spans.End; } } @@ -215,7 +212,6 @@ namespace Lucene.Net.Search.Spans } // TODO: Remove warning after API has been finalized - public override bool IsPayloadAvailable { get http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/SpanPositionRangeQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/SpanPositionRangeQuery.cs b/src/Lucene.Net/Search/Spans/SpanPositionRangeQuery.cs index dc54154..4eb3285 100644 --- a/src/Lucene.Net/Search/Spans/SpanPositionRangeQuery.cs +++ b/src/Lucene.Net/Search/Spans/SpanPositionRangeQuery.cs @@ -25,9 +25,9 @@ namespace Lucene.Net.Search.Spans using ToStringUtils = Lucene.Net.Util.ToStringUtils; /// <summary> - /// Checks to see if the <seealso cref="#getMatch()"/> lies between a start and end position + /// Checks to see if the <see cref="SpanPositionCheckQuery.Match"/> lies between a start and end position /// </summary> - /// <seealso cref= Lucene.Net.Search.Spans.SpanFirstQuery for a derivation that is optimized for the case where start position is 0 </seealso> + /// <seealso cref="Lucene.Net.Search.Spans.SpanFirstQuery">for a derivation that is optimized for the case where start position is 0</seealso> #if FEATURE_SERIALIZABLE [Serializable] #endif @@ -69,7 +69,7 @@ namespace Lucene.Net.Search.Spans } } - /// <returns> the maximum end position permitted in a match. </returns> + /// <returns> The maximum end position permitted in a match. </returns> public virtual int End { get http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/SpanQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/SpanQuery.cs b/src/Lucene.Net/Search/Spans/SpanQuery.cs index 2ec08fd..976b343 100644 --- a/src/Lucene.Net/Search/Spans/SpanQuery.cs +++ b/src/Lucene.Net/Search/Spans/SpanQuery.cs @@ -40,8 +40,8 @@ namespace Lucene.Net.Search.Spans /// <summary> /// Returns the name of the field matched by this query. - /// <p> - /// Note that this may return null if the query matches no terms. + /// <para/> + /// Note that this may return <c>null</c> if the query matches no terms. /// </summary> public abstract string Field { get; } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/SpanScorer.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/SpanScorer.cs b/src/Lucene.Net/Search/Spans/SpanScorer.cs index 7590003..cf13628 100644 --- a/src/Lucene.Net/Search/Spans/SpanScorer.cs +++ b/src/Lucene.Net/Search/Spans/SpanScorer.cs @@ -110,7 +110,8 @@ namespace Lucene.Net.Search.Spans /// <summary> /// Returns the intermediate "sloppy freq" adjusted for edit distance - /// @lucene.internal + /// <para/> + /// @lucene.internal /// </summary> // only public so .payloads can see it. public virtual float SloppyFreq http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/SpanTermQuery.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/SpanTermQuery.cs b/src/Lucene.Net/Search/Spans/SpanTermQuery.cs index d053dbd..71bd0c5 100644 --- a/src/Lucene.Net/Search/Spans/SpanTermQuery.cs +++ b/src/Lucene.Net/Search/Spans/SpanTermQuery.cs @@ -43,7 +43,7 @@ namespace Lucene.Net.Search.Spans protected Term m_term; /// <summary> - /// Construct a SpanTermQuery matching the named term's spans. </summary> + /// Construct a <see cref="SpanTermQuery"/> matching the named term's spans. </summary> public SpanTermQuery(Term term) { this.m_term = term; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/396db51b/src/Lucene.Net/Search/Spans/Spans.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Search/Spans/Spans.cs b/src/Lucene.Net/Search/Spans/Spans.cs index abd9e38..df9ef5d 100644 --- a/src/Lucene.Net/Search/Spans/Spans.cs +++ b/src/Lucene.Net/Search/Spans/Spans.cs @@ -32,25 +32,29 @@ namespace Lucene.Net.Search.Spans public abstract class Spans { /// <summary> - /// Move to the next match, returning true iff any such exists. </summary> + /// Move to the next match, returning true if any such exists. </summary> public abstract bool Next(); /// <summary> /// Skips to the first match beyond the current, whose document number is /// greater than or equal to <i>target</i>. - /// <p>The behavior of this method is <b>undefined</b> when called with - /// <code> target <= current</code>, or after the iterator has exhausted. + /// <para/>The behavior of this method is <b>undefined</b> when called with + /// <c> target <= current</c>, or after the iterator has exhausted. /// Both cases may result in unpredicted behavior. - /// <p>Returns true iff there is such - /// a match. <p>Behaves as if written: <pre class="prettyprint"> - /// boolean skipTo(int target) { - /// do { - /// if (!next()) - /// return false; - /// } while (target > doc()); - /// return true; - /// } - /// </pre> + /// <para/>Returns <c>true</c> if there is such + /// a match. + /// <para/>Behaves as if written: + /// <code> + /// bool SkipTo(int target) + /// { + /// do + /// { + /// if (!Next()) + /// return false; + /// } while (target > Doc); + /// return true; + /// } + /// </code> /// Most implementations are considerably more efficient than that. /// </summary> public abstract bool SkipTo(int target); @@ -69,38 +73,39 @@ namespace Lucene.Net.Search.Spans /// <summary> /// Returns the payload data for the current span. - /// this is invalid until <seealso cref="#next()"/> is called for + /// this is invalid until <see cref="Next()"/> is called for /// the first time. - /// this method must not be called more than once after each call - /// of <seealso cref="#next()"/>. However, most payloads are loaded lazily, + /// This method must not be called more than once after each call + /// of <see cref="Next()"/>. However, most payloads are loaded lazily, /// so if the payload data for the current position is not needed, /// this method may not be called at all for performance reasons. An ordered /// SpanQuery does not lazy load, so if you have payloads in your index and /// you do not want ordered SpanNearQuerys to collect payloads, you can - /// disable collection with a constructor option.<br> - /// <br> + /// disable collection with a constructor option. + /// <para/> /// Note that the return type is a collection, thus the ordering should not be relied upon. - /// <br/> + /// <para/> /// @lucene.experimental /// </summary> - /// <returns> a List of byte arrays containing the data of this payload, otherwise null if isPayloadAvailable is false </returns> - /// <exception cref="IOException"> if there is a low-level I/O error </exception> + /// <returns> A <see cref="T:ICollection{byte[]}"/> of byte arrays containing the data of this payload, + /// otherwise <c>null</c> if <see cref="IsPayloadAvailable"/> is <c>false</c> </returns> + /// <exception cref="System.IO.IOException"> if there is a low-level I/O error </exception> // TODO: Remove warning after API has been finalized public abstract ICollection<byte[]> GetPayload(); /// <summary> /// Checks if a payload can be loaded at this position. - /// <p/> + /// <para/> /// Payloads can only be loaded once per call to - /// <seealso cref="#next()"/>. + /// <see cref="Next()"/>. /// </summary> - /// <returns> true if there is a payload available at this position that can be loaded </returns> + /// <returns> <c>true</c> if there is a payload available at this position that can be loaded </returns> public abstract bool IsPayloadAvailable { get; } /// <summary> /// Returns the estimated cost of this spans. - /// <p> - /// this is generally an upper bound of the number of documents this iterator + /// <para/> + /// This is generally an upper bound of the number of documents this iterator /// might match, but may be a rough heuristic, hardcoded value, or otherwise /// completely inaccurate. /// </summary>
