Lucene.Net.Core.Index (AtomicReader + AtomicReaderContext): documentation comments
Project: http://git-wip-us.apache.org/repos/asf/lucenenet/repo Commit: http://git-wip-us.apache.org/repos/asf/lucenenet/commit/f6c7515c Tree: http://git-wip-us.apache.org/repos/asf/lucenenet/tree/f6c7515c Diff: http://git-wip-us.apache.org/repos/asf/lucenenet/diff/f6c7515c Branch: refs/heads/api-work Commit: f6c7515c8ff4e483538257d450f25776f3d9f1de Parents: 631cfa7 Author: Shad Storhaug <[email protected]> Authored: Fri Mar 24 02:11:34 2017 +0700 Committer: Shad Storhaug <[email protected]> Committed: Fri Mar 24 06:28:22 2017 +0700 ---------------------------------------------------------------------- src/Lucene.Net.Core/Index/AtomicReader.cs | 129 ++++++++++--------- .../Index/AtomicReaderContext.cs | 4 +- 2 files changed, 70 insertions(+), 63 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/lucenenet/blob/f6c7515c/src/Lucene.Net.Core/Index/AtomicReader.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Index/AtomicReader.cs b/src/Lucene.Net.Core/Index/AtomicReader.cs index 3d5260a..3e4f1eb 100644 --- a/src/Lucene.Net.Core/Index/AtomicReader.cs +++ b/src/Lucene.Net.Core/Index/AtomicReader.cs @@ -24,26 +24,26 @@ namespace Lucene.Net.Index using IBits = Lucene.Net.Util.IBits; /// <summary> - /// {@code AtomicReader} is an abstract class, providing an interface for accessing an + /// <see cref="AtomicReader"/> is an abstract class, providing an interface for accessing an /// index. Search of an index is done entirely through this abstract interface, - /// so that any subclass which implements it is searchable. IndexReaders implemented + /// so that any subclass which implements it is searchable. <see cref="IndexReader"/>s implemented /// by this subclass do not consist of several sub-readers, /// they are atomic. They support retrieval of stored fields, doc values, terms, /// and postings. /// - /// <p>For efficiency, in this API documents are often referred to via + /// <para/>For efficiency, in this API documents are often referred to via /// <i>document numbers</i>, non-negative integers which each name a unique /// document in the index. These document numbers are ephemeral -- they may change /// as documents are added to and deleted from an index. Clients should thus not /// rely on a given document having the same number between sessions. /// - /// <p> - /// <a name="thread-safety"></a><p><b>NOTE</b>: {@link - /// IndexReader} instances are completely thread + /// <para/> + /// <b>NOTE</b>: <see cref="IndexReader"/> + /// instances are completely thread /// safe, meaning multiple threads can call any of its methods, /// concurrently. If your application requires external /// synchronization, you should <b>not</b> synchronize on the - /// <code>IndexReader</code> instance; use your own + /// <see cref="IndexReader"/> instance; use your own /// (non-Lucene) objects instead. /// </summary> public abstract class AtomicReader : IndexReader @@ -57,9 +57,9 @@ namespace Lucene.Net.Index /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> - protected internal AtomicReader() + protected AtomicReader() : base() { InitializeInstanceFields(); @@ -74,6 +74,11 @@ namespace Lucene.Net.Index } } + /// <summary> + /// LUCENENET specific propety that allows access to + /// the context as <see cref="AtomicReaderContext"/>, + /// which prevents the need to cast. + /// </summary> public AtomicReaderContext AtomicContext { get @@ -84,9 +89,8 @@ namespace Lucene.Net.Index } /// <summary> - /// Returns true if there are norms stored for this field. </summary> - /// @deprecated (4.0) use <seealso cref="#getFieldInfos()"/> and check <seealso cref="FieldInfo#hasNorms()"/> - /// for the field instead. + /// Returns true if there are norms stored for this <paramref name="field"/>. + /// </summary> [Obsolete("(4.0) use FieldInfos and check FieldInfo.HasNorms for the field instead.")] public bool HasNorms(string field) { @@ -97,8 +101,8 @@ namespace Lucene.Net.Index } /// <summary> - /// Returns <seealso cref="Fields"/> for this reader. - /// this method may return null if the reader has no + /// Returns <see cref="Index.Fields"/> for this reader. + /// this property may return <c>null</c> if the reader has no /// postings. /// </summary> public abstract Fields Fields { get; } @@ -127,9 +131,9 @@ namespace Lucene.Net.Index } /// <summary> - /// Returns the number of documents containing the term - /// <code>t</code>. this method returns 0 if the term or - /// field does not exists. this method does not take into + /// Returns the number of documents containing the <paramref name="term"/>. + /// This method returns 0 if the term or + /// field does not exist. This method does not take into /// account deleted documents that have not yet been merged /// away. /// </summary> @@ -187,7 +191,7 @@ namespace Lucene.Net.Index } /// <summary> - /// this may return null if the field does not exist. </summary> + /// This may return <c>null</c> if the field does not exist. </summary> public Terms GetTerms(string field) // LUCENENET specific: Renamed from Terms() { Fields fields = Fields; @@ -199,10 +203,11 @@ namespace Lucene.Net.Index } /// <summary> - /// Returns <seealso cref="DocsEnum"/> for the specified term. - /// this will return null if either the field or - /// term does not exist. </summary> - /// <seealso cref= TermsEnum#docs(Bits, DocsEnum) </seealso> + /// Returns <see cref="DocsEnum"/> for the specified term. + /// This will return <c>null</c> if either the field or + /// term does not exist. + /// </summary> + /// <seealso cref="TermsEnum.Docs(IBits, DocsEnum)"/> public DocsEnum GetTermDocsEnum(Term term) // LUCENENET specific: Renamed from TermDocsEnum() { Debug.Assert(term.Field != null); @@ -224,10 +229,10 @@ namespace Lucene.Net.Index } /// <summary> - /// Returns <seealso cref="DocsAndPositionsEnum"/> for the specified - /// term. this will return null if the - /// field or term does not exist or positions weren't indexed. </summary> - /// <seealso cref= TermsEnum#docsAndPositions(Bits, DocsAndPositionsEnum) </seealso> + /// Returns <see cref="DocsAndPositionsEnum"/> for the specified + /// term. This will return <c>null</c> if the + /// field or term does not exist or positions weren't indexed. </summary> + /// <seealso cref="TermsEnum.DocsAndPositions(IBits, DocsAndPositionsEnum)"/> public DocsAndPositionsEnum GetTermPositionsEnum(Term term) // LUCENENET specific: Renamed from TermPositionsEnum() { Debug.Assert(term.Field != null); @@ -249,78 +254,80 @@ namespace Lucene.Net.Index } /// <summary> - /// Returns <seealso cref="NumericDocValues"/> for this field, or - /// null if no <seealso cref="NumericDocValues"/> were indexed for - /// this field. The returned instance should only be - /// used by a single thread. + /// Returns <see cref="NumericDocValues"/> for this field, or + /// null if no <see cref="NumericDocValues"/> were indexed for + /// this field. The returned instance should only be + /// used by a single thread. /// </summary> public abstract NumericDocValues GetNumericDocValues(string field); /// <summary> - /// Returns <seealso cref="BinaryDocValues"/> for this field, or - /// null if no <seealso cref="BinaryDocValues"/> were indexed for - /// this field. The returned instance should only be - /// used by a single thread. + /// Returns <see cref="BinaryDocValues"/> for this field, or + /// <c>null</c> if no <see cref="BinaryDocValues"/> were indexed for + /// this field. The returned instance should only be + /// used by a single thread. /// </summary> public abstract BinaryDocValues GetBinaryDocValues(string field); /// <summary> - /// Returns <seealso cref="SortedDocValues"/> for this field, or - /// null if no <seealso cref="SortedDocValues"/> were indexed for - /// this field. The returned instance should only be - /// used by a single thread. + /// Returns <see cref="SortedDocValues"/> for this field, or + /// <c>null</c> if no <see cref="SortedDocValues"/> were indexed for + /// this field. The returned instance should only be + /// used by a single thread. /// </summary> public abstract SortedDocValues GetSortedDocValues(string field); /// <summary> - /// Returns <seealso cref="SortedSetDocValues"/> for this field, or - /// null if no <seealso cref="SortedSetDocValues"/> were indexed for - /// this field. The returned instance should only be - /// used by a single thread. + /// Returns <see cref="SortedSetDocValues"/> for this field, or + /// <c>null</c> if no <see cref="SortedSetDocValues"/> were indexed for + /// this field. The returned instance should only be + /// used by a single thread. /// </summary> public abstract SortedSetDocValues GetSortedSetDocValues(string field); /// <summary> - /// Returns a <seealso cref="IBits"/> at the size of <code>reader.maxDoc()</code>, - /// with turned on bits for each docid that does have a value for this field, - /// or null if no DocValues were indexed for this field. The - /// returned instance should only be used by a single thread + /// Returns a <see cref="IBits"/> at the size of <c>reader.MaxDoc</c>, + /// with turned on bits for each docid that does have a value for this field, + /// or <c>null</c> if no <see cref="DocValues"/> were indexed for this field. The + /// returned instance should only be used by a single thread. /// </summary> public abstract IBits GetDocsWithField(string field); /// <summary> - /// Returns <seealso cref="NumericDocValues"/> representing norms - /// for this field, or null if no <seealso cref="NumericDocValues"/> - /// were indexed. The returned instance should only be - /// used by a single thread. + /// Returns <see cref="NumericDocValues"/> representing norms + /// for this field, or <c>null</c> if no <see cref="NumericDocValues"/> + /// were indexed. The returned instance should only be + /// used by a single thread. /// </summary> public abstract NumericDocValues GetNormValues(string field); /// <summary> - /// Get the <seealso cref="FieldInfos"/> describing all fields in + /// Get the <see cref="Index.FieldInfos"/> describing all fields in /// this reader. + /// <para/> /// @lucene.experimental /// </summary> public abstract FieldInfos FieldInfos { get; } /// <summary> - /// Returns the <seealso cref="IBits"/> representing live (not - /// deleted) docs. A set bit indicates the doc ID has not - /// been deleted. If this method returns null it means - /// there are no deleted documents (all documents are - /// live). - /// - /// The returned instance has been safely published for - /// use by multiple threads without additional - /// synchronization. + /// Returns the <see cref="IBits"/> representing live (not + /// deleted) docs. A set bit indicates the doc ID has not + /// been deleted. If this method returns <c>null</c> it means + /// there are no deleted documents (all documents are + /// live). + /// <para/> + /// The returned instance has been safely published for + /// use by multiple threads without additional + /// synchronization. /// </summary> public abstract IBits LiveDocs { get; } /// <summary> /// Checks consistency of this reader. - /// <p> + /// <para/> /// Note that this may be costly in terms of I/O, e.g. /// may involve computing a checksum value against large data files. + /// <para/> /// @lucene.internal /// </summary> public abstract void CheckIntegrity(); http://git-wip-us.apache.org/repos/asf/lucenenet/blob/f6c7515c/src/Lucene.Net.Core/Index/AtomicReaderContext.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net.Core/Index/AtomicReaderContext.cs b/src/Lucene.Net.Core/Index/AtomicReaderContext.cs index 8f7d2eb..5551c6d 100644 --- a/src/Lucene.Net.Core/Index/AtomicReaderContext.cs +++ b/src/Lucene.Net.Core/Index/AtomicReaderContext.cs @@ -21,7 +21,7 @@ namespace Lucene.Net.Index */ /// <summary> - /// <seealso cref="IndexReaderContext"/> for <seealso cref="AtomicReader"/> instances. + /// <see cref="IndexReaderContext"/> for <see cref="Index.AtomicReader"/> instances. /// </summary> public sealed class AtomicReaderContext : IndexReaderContext { @@ -37,7 +37,7 @@ namespace Lucene.Net.Index private readonly IList<AtomicReaderContext> leaves; /// <summary> - /// Creates a new <seealso cref="AtomicReaderContext"/> + /// Creates a new <see cref="AtomicReaderContext"/> /// </summary> internal AtomicReaderContext(CompositeReaderContext parent, AtomicReader reader, int ord, int docBase, int leafOrd, int leafDocBase) : base(parent, ord, docBase)
