http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/FieldsProducer.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/FieldsProducer.cs b/src/Lucene.Net/Codecs/FieldsProducer.cs index d2b8f8a..5b9067b 100644 --- a/src/Lucene.Net/Codecs/FieldsProducer.cs +++ b/src/Lucene.Net/Codecs/FieldsProducer.cs @@ -23,39 +23,45 @@ namespace Lucene.Net.Codecs /// <summary> /// Abstract API that produces terms, doc, freq, prox, offset and - /// payloads postings. - /// + /// payloads postings. + /// <para/> /// @lucene.experimental /// </summary> - public abstract class FieldsProducer : Fields, IDisposable { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal FieldsProducer() { } // LUCENENET specific - implementing proper dispose pattern + /// <summary> + /// Disposes all resources used by this object. + /// </summary> public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } + /// <summary> + /// Implementations must override and should dispose all resources used by this instance. + /// </summary> protected abstract void Dispose(bool disposing); /// <summary> - /// Returns approximate RAM bytes used </summary> + /// Returns approximate RAM bytes used. </summary> public abstract long RamBytesUsed(); /// <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/a08ae945/src/Lucene.Net/Codecs/FilterCodec.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/FilterCodec.cs b/src/Lucene.Net/Codecs/FilterCodec.cs index 81168f9..709545f 100644 --- a/src/Lucene.Net/Codecs/FilterCodec.cs +++ b/src/Lucene.Net/Codecs/FilterCodec.cs @@ -19,30 +19,32 @@ namespace Lucene.Net.Codecs /// <summary> /// A codec that forwards all its method calls to another codec. - /// <p> + /// <para/> /// Extend this class when you need to reuse the functionality of an existing /// codec. For example, if you want to build a codec that redefines Lucene46's - /// <seealso cref="LiveDocsFormat"/>: - /// <pre class="prettyprint"> - /// public final class CustomCodec extends FilterCodec { + /// <see cref="Codecs.LiveDocsFormat"/>: + /// <code> + /// public sealed class CustomCodec : FilterCodec + /// { + /// public CustomCodec() + /// : base("CustomCodec", new Lucene46Codec()) + /// { + /// } /// - /// public CustomCodec() { - /// super("CustomCodec", new Lucene46Codec()); + /// public override LiveDocsFormat LiveDocsFormat + /// { + /// get { return new CustomLiveDocsFormat(); } + /// } /// } + /// </code> /// - /// public LiveDocsFormat liveDocsFormat() { - /// return new CustomLiveDocsFormat(); - /// } - /// - /// } - /// </pre> - /// - /// <p><em>Please note:</em> Don't call <seealso cref="Codec#forName"/> from - /// the no-arg constructor of your own codec. When the SPI framework - /// loads your own Codec as SPI component, SPI has not yet fully initialized! - /// If you want to extend another Codec, instantiate it directly by calling + /// <para/> + /// <em>Please note:</em> Don't call <see cref="Codec.ForName(string)"/> from + /// the no-arg constructor of your own codec. When the <see cref="DefaultCodecFactory"/> + /// loads your own <see cref="Codec"/>, the <see cref="DefaultCodecFactory"/> has not yet fully initialized! + /// If you want to extend another <see cref="Codec"/>, instantiate it directly by calling /// its constructor. - /// + /// <para/> /// @lucene.experimental /// </summary> public abstract class FilterCodec : Codec http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/LiveDocsFormat.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/LiveDocsFormat.cs b/src/Lucene.Net/Codecs/LiveDocsFormat.cs index 3b5ba40..fb377a6 100644 --- a/src/Lucene.Net/Codecs/LiveDocsFormat.cs +++ b/src/Lucene.Net/Codecs/LiveDocsFormat.cs @@ -26,14 +26,15 @@ namespace Lucene.Net.Codecs using SegmentCommitInfo = Lucene.Net.Index.SegmentCommitInfo; /// <summary> - /// Format for live/deleted documents + /// Format for live/deleted documents. + /// <para/> /// @lucene.experimental /// </summary> public abstract class LiveDocsFormat { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal LiveDocsFormat() { @@ -52,14 +53,14 @@ namespace Lucene.Net.Codecs public abstract IBits ReadLiveDocs(Directory dir, SegmentCommitInfo info, IOContext context); /// <summary> - /// Persist live docs bits. Use {@link - /// SegmentCommitInfo#getNextDelGen} to determine the - /// generation of the deletes file you should write to. + /// Persist live docs bits. Use + /// <see cref="SegmentCommitInfo.NextDelGen"/> to determine the + /// generation of the deletes file you should write to. /// </summary> public abstract void WriteLiveDocs(IMutableBits bits, Directory dir, SegmentCommitInfo info, int newDelCount, IOContext context); /// <summary> - /// Records all files in use by this <seealso cref="SegmentCommitInfo"/> into the files argument. </summary> + /// Records all files in use by this <see cref="SegmentCommitInfo"/> into the files argument. </summary> public abstract void Files(SegmentCommitInfo info, ICollection<string> files); } } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/Lucene41/Lucene41PostingsFormat.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/Lucene41/Lucene41PostingsFormat.cs b/src/Lucene.Net/Codecs/Lucene41/Lucene41PostingsFormat.cs index 8b0c6ea..e591999 100644 --- a/src/Lucene.Net/Codecs/Lucene41/Lucene41PostingsFormat.cs +++ b/src/Lucene.Net/Codecs/Lucene41/Lucene41PostingsFormat.cs @@ -35,10 +35,10 @@ namespace Lucene.Net.Codecs.Lucene41 /// <ul> /// <li> /// <b>Packed Blocks and VInt Blocks</b>: - /// <p>In packed blocks, integers are encoded with the same bit width (<seealso cref="PackedInts packed format"/>): + /// <p>In packed blocks, integers are encoded with the same bit width packed format (<see cref="Util.Packed.PackedInt32s"/>): /// the block size (i.e. number of integers inside block) is fixed (currently 128). Additionally blocks /// that are all the same value are encoded in an optimized way.</p> - /// <p>In VInt blocks, integers are encoded as <seealso cref="DataOutput#writeVInt VInt"/>: + /// <p>In VInt blocks, integers are encoded as VInt (<see cref="Store.DataOutput.WriteVInt32(int)"/>): /// the block size is variable.</p> /// </li> /// http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/MappingMultiDocsAndPositionsEnum.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/MappingMultiDocsAndPositionsEnum.cs b/src/Lucene.Net/Codecs/MappingMultiDocsAndPositionsEnum.cs index 15daee5..5c4d346 100644 --- a/src/Lucene.Net/Codecs/MappingMultiDocsAndPositionsEnum.cs +++ b/src/Lucene.Net/Codecs/MappingMultiDocsAndPositionsEnum.cs @@ -28,7 +28,7 @@ namespace Lucene.Net.Codecs /// <summary> /// Exposes flex API, merged from flex API of sub-segments, /// remapping docIDs (this is used for segment merging). - /// + /// <para/> /// @lucene.experimental /// </summary> public sealed class MappingMultiDocsAndPositionsEnum : DocsAndPositionsEnum @@ -58,8 +58,8 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Sets the <seealso cref="MergeState"/>, which is used to re-map - /// document IDs. + /// Gets or Sets the <see cref="Index.MergeState"/>, which is used to re-map + /// document IDs. /// </summary> public MergeState MergeState { @@ -75,7 +75,7 @@ namespace Lucene.Net.Codecs /// <summary> /// How many sub-readers we are merging. </summary> - /// <seealso cref= #getSubs </seealso> + /// <seealso cref="Subs"/> public int NumSubs { get http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/MappingMultiDocsEnum.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/MappingMultiDocsEnum.cs b/src/Lucene.Net/Codecs/MappingMultiDocsEnum.cs index b16b2ab..8074346 100644 --- a/src/Lucene.Net/Codecs/MappingMultiDocsEnum.cs +++ b/src/Lucene.Net/Codecs/MappingMultiDocsEnum.cs @@ -28,7 +28,7 @@ namespace Lucene.Net.Codecs /// <summary> /// Exposes flex API, merged from flex API of sub-segments, /// remapping docIDs (this is used for segment merging). - /// + /// <para/> /// @lucene.experimental /// </summary> public sealed class MappingMultiDocsEnum : DocsEnum @@ -58,8 +58,8 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Sets the <seealso cref="MergeState"/>, which is used to re-map - /// document IDs. + /// Sets the <see cref="MergeState"/>, which is used to re-map + /// document IDs. /// </summary> public MergeState MergeState { @@ -75,7 +75,7 @@ namespace Lucene.Net.Codecs /// <summary> /// How many sub-readers we are merging. </summary> - /// <seealso cref= #getSubs </seealso> + /// <seealso cref="Subs"/> public int NumSubs { get http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/MultiLevelSkipListReader.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/MultiLevelSkipListReader.cs b/src/Lucene.Net/Codecs/MultiLevelSkipListReader.cs index 0399aaa..63d25f9 100644 --- a/src/Lucene.Net/Codecs/MultiLevelSkipListReader.cs +++ b/src/Lucene.Net/Codecs/MultiLevelSkipListReader.cs @@ -25,20 +25,20 @@ namespace Lucene.Net.Codecs using MathUtil = Lucene.Net.Util.MathUtil; /// <summary> - /// this abstract class reads skip lists with multiple levels. - /// - /// See <seealso cref="MultiLevelSkipListWriter"/> for the information about the encoding + /// This abstract class reads skip lists with multiple levels. + /// <para/> + /// See <see cref="MultiLevelSkipListWriter"/> for the information about the encoding /// of the multi level skip lists. - /// - /// Subclasses must implement the abstract method <seealso cref="#readSkipData(int, IndexInput)"/> + /// <para/> + /// Subclasses must implement the abstract method <see cref="ReadSkipData(int, IndexInput)"/> /// which defines the actual format of the skip data. + /// <para/> /// @lucene.experimental /// </summary> - public abstract class MultiLevelSkipListReader : IDisposable { /// <summary> - /// the maximum number of skip levels possible for this index </summary> + /// The maximum number of skip levels possible for this index. </summary> protected internal int m_maxNumberOfSkipLevels; // number of levels in this skip list @@ -57,7 +57,7 @@ namespace Lucene.Net.Codecs private bool haveSkipped; /// <summary> - /// skipStream for each level. </summary> + /// SkipStream for each level. </summary> private IndexInput[] skipStream; /// <summary> @@ -65,7 +65,7 @@ namespace Lucene.Net.Codecs private long[] skipPointer; /// <summary> - /// skipInterval of each level. </summary> + /// SkipInterval of each level. </summary> private int[] skipInterval; /// <summary> @@ -86,7 +86,7 @@ namespace Lucene.Net.Codecs /// <summary> /// childPointer of last read skip entry with docId <= - /// target. + /// target. /// </summary> private long lastChildPointer; @@ -94,7 +94,7 @@ namespace Lucene.Net.Codecs private readonly int skipMultiplier; /// <summary> - /// Creates a {@code MultiLevelSkipListReader}. </summary> + /// Creates a <see cref="MultiLevelSkipListReader"/>. </summary> protected MultiLevelSkipListReader(IndexInput skipStream, int maxSkipLevels, int skipInterval, int skipMultiplier) { this.skipStream = new IndexInput[maxSkipLevels]; @@ -116,9 +116,9 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Creates a {@code MultiLevelSkipListReader}, where - /// {@code skipInterval} and {@code skipMultiplier} are - /// the same. + /// Creates a <see cref="MultiLevelSkipListReader"/>, where + /// <see cref="skipInterval"/> and <see cref="skipMultiplier"/> are + /// the same. /// </summary> protected internal MultiLevelSkipListReader(IndexInput skipStream, int maxSkipLevels, int skipInterval) : this(skipStream, maxSkipLevels, skipInterval, skipInterval) @@ -126,8 +126,8 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Returns the id of the doc to which the last call of <seealso cref="#skipTo(int)"/> - /// has skipped. + /// Returns the id of the doc to which the last call of <see cref="SkipTo(int)"/> + /// has skipped. /// </summary> public virtual int Doc { @@ -139,7 +139,7 @@ namespace Lucene.Net.Codecs /// <summary> /// Skips entries to the first beyond the current whose document number is - /// greater than or equal to <i>target</i>. Returns the current doc count. + /// greater than or equal to <paramref name="target"/>. Returns the current doc count. /// </summary> public virtual int SkipTo(int target) { @@ -213,7 +213,7 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Seeks the skip entry on the given level </summary> + /// Seeks the skip entry on the given level. </summary> protected virtual void SeekChild(int level) { skipStream[level].Seek(lastChildPointer); @@ -225,7 +225,10 @@ namespace Lucene.Net.Codecs } } - public void Dispose() + /// <summary> + /// Disposes all resources used by this object. + /// </summary> + public void Dispose() // LUCENENET TODO: API - implement dispose pattern { for (int i = 1; i < skipStream.Length; i++) { @@ -255,7 +258,7 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Loads the skip levels </summary> + /// Loads the skip levels. </summary> private void LoadSkipLevels() { if (docCount <= skipInterval[0]) @@ -310,12 +313,12 @@ namespace Lucene.Net.Codecs /// <summary> /// Subclasses must implement the actual skip data encoding in this method. /// </summary> - /// <param name="level"> the level skip data shall be read from </param> - /// <param name="skipStream"> the skip stream to read from </param> + /// <param name="level"> The level skip data shall be read from. </param> + /// <param name="skipStream"> The skip stream to read from. </param> protected abstract int ReadSkipData(int level, IndexInput skipStream); /// <summary> - /// Copies the values of the last read skip entry on this <paramref name="level"/> </summary> + /// Copies the values of the last read skip entry on this <paramref name="level"/>. </summary> protected virtual void SetLastSkipData(int level) { lastDoc = m_skipDoc[level]; @@ -323,7 +326,7 @@ namespace Lucene.Net.Codecs } /// <summary> - /// used to buffer the top skip levels </summary> + /// Used to buffer the top skip levels. </summary> private sealed class SkipBuffer : IndexInput { private byte[] data; http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/MultiLevelSkipListWriter.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/MultiLevelSkipListWriter.cs b/src/Lucene.Net/Codecs/MultiLevelSkipListWriter.cs index d7fe18b..2c5e960 100644 --- a/src/Lucene.Net/Codecs/MultiLevelSkipListWriter.cs +++ b/src/Lucene.Net/Codecs/MultiLevelSkipListWriter.cs @@ -24,9 +24,9 @@ namespace Lucene.Net.Codecs using RAMOutputStream = Lucene.Net.Store.RAMOutputStream; /// <summary> - /// this abstract class writes skip lists with multiple levels. + /// This abstract class writes skip lists with multiple levels. /// - /// <pre> + /// <code> /// /// Example for skipInterval = 3: /// c (skip level 2) @@ -47,30 +47,30 @@ namespace Lucene.Net.Codecs /// /// While this class takes care of writing the different skip levels, /// subclasses must define the actual format of the skip data. - /// </pre> + /// </code> + /// <para/> /// @lucene.experimental /// </summary> - public abstract class MultiLevelSkipListWriter { /// <summary> - /// number of levels in this skip list </summary> + /// Number of levels in this skip list. </summary> protected internal int m_numberOfSkipLevels; /// <summary> - /// the skip interval in the list with level = 0 </summary> + /// The skip interval in the list with level = 0. </summary> private int skipInterval; /// <summary> - /// skipInterval used for level > 0 </summary> + /// SkipInterval used for level > 0. </summary> private int skipMultiplier; /// <summary> - /// for every skip level a different buffer is used </summary> + /// For every skip level a different buffer is used. </summary> private RAMOutputStream[] skipBuffer; /// <summary> - /// Creates a {@code MultiLevelSkipListWriter}. </summary> + /// Creates a <see cref="MultiLevelSkipListWriter"/>. </summary> protected MultiLevelSkipListWriter(int skipInterval, int skipMultiplier, int maxSkipLevels, int df) { this.skipInterval = skipInterval; @@ -94,9 +94,9 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Creates a {@code MultiLevelSkipListWriter}, where - /// {@code skipInterval} and {@code skipMultiplier} are - /// the same. + /// Creates a <see cref="MultiLevelSkipListWriter"/>{@code }, where + /// <see cref="skipInterval"/> and <see cref="skipMultiplier"/> are + /// the same. /// </summary> protected MultiLevelSkipListWriter(int skipInterval, int maxSkipLevels, int df) : this(skipInterval, skipInterval, maxSkipLevels, df) @@ -115,7 +115,7 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Creates new buffers or empties the existing ones </summary> + /// Creates new buffers or empties the existing ones. </summary> public virtual void ResetSkip() { if (skipBuffer == null) @@ -134,16 +134,16 @@ namespace Lucene.Net.Codecs /// <summary> /// Subclasses must implement the actual skip data encoding in this method. /// </summary> - /// <param name="level"> the level skip data shall be writing for </param> - /// <param name="skipBuffer"> the skip buffer to write to </param> + /// <param name="level"> The level skip data shall be writing for. </param> + /// <param name="skipBuffer"> The skip buffer to write to. </param> protected abstract void WriteSkipData(int level, IndexOutput skipBuffer); /// <summary> /// Writes the current skip data to the buffers. The current document frequency determines /// the max level is skip data is to be written to. /// </summary> - /// <param name="df"> the current document frequency </param> - /// <exception cref="IOException"> If an I/O error occurs </exception> + /// <param name="df"> The current document frequency. </param> + /// <exception cref="System.IO.IOException"> If an I/O error occurs. </exception> public virtual void BufferSkip(int df) { Debug.Assert(df % skipInterval == 0); @@ -179,8 +179,8 @@ namespace Lucene.Net.Codecs /// <summary> /// Writes the buffered skip lists to the given output. /// </summary> - /// <param name="output"> the IndexOutput the skip lists shall be written to </param> - /// <returns> the pointer the skip list starts </returns> + /// <param name="output"> The <see cref="IndexOutput"/> the skip lists shall be written to. </param> + /// <returns> The pointer the skip list starts. </returns> public virtual long WriteSkip(IndexOutput output) { long skipPointer = output.GetFilePointer(); http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/NormsFormat.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/NormsFormat.cs b/src/Lucene.Net/Codecs/NormsFormat.cs index 0bb97a9..c295444 100644 --- a/src/Lucene.Net/Codecs/NormsFormat.cs +++ b/src/Lucene.Net/Codecs/NormsFormat.cs @@ -27,26 +27,26 @@ namespace Lucene.Net.Codecs { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal NormsFormat() { } /// <summary> - /// Returns a <seealso cref="DocValuesConsumer"/> to write norms to the - /// index. + /// Returns a <see cref="DocValuesConsumer"/> to write norms to the + /// index. /// </summary> public abstract DocValuesConsumer NormsConsumer(SegmentWriteState state); /// <summary> - /// Returns a <seealso cref="DocValuesProducer"/> to read norms from the index. - /// <p> + /// Returns a <see cref="DocValuesProducer"/> to read norms from the index. + /// <para/> /// NOTE: by the time this call returns, it must hold open any files it will /// need to use; else, those files may be deleted. Additionally, required files /// may be deleted during the execution of this call before there is a chance - /// to open them. Under these circumstances an IOException should be thrown by - /// the implementation. IOExceptions are expected and will automatically cause + /// to open them. Under these circumstances an <see cref="System.IO.IOException"/> should be thrown by + /// the implementation. <see cref="System.IO.IOException"/> are expected and will automatically cause /// a retry of the segment opening logic with the newly revised segments. /// </summary> public abstract DocValuesProducer NormsProducer(SegmentReadState state); http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/PostingsBaseFormat.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/PostingsBaseFormat.cs b/src/Lucene.Net/Codecs/PostingsBaseFormat.cs index f9b4876..a783fa5 100644 --- a/src/Lucene.Net/Codecs/PostingsBaseFormat.cs +++ b/src/Lucene.Net/Codecs/PostingsBaseFormat.cs @@ -21,9 +21,9 @@ namespace Lucene.Net.Codecs using SegmentWriteState = Lucene.Net.Index.SegmentWriteState; /// <summary> - /// Provides a <seealso cref="PostingsReaderBase"/> and {@link - /// PostingsWriterBase}. - /// + /// Provides a <see cref="Codecs.PostingsReaderBase"/> and + /// <see cref="Codecs.PostingsWriterBase"/>. + /// <para/> /// @lucene.experimental /// </summary> @@ -37,7 +37,7 @@ namespace Lucene.Net.Codecs { /// <summary> /// Unique name that's used to retrieve this codec when - /// reading the index + /// reading the index. /// </summary> public string Name { get; private set; } @@ -49,14 +49,14 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Creates the <seealso cref="PostingsReaderBase"/> for this - /// format. + /// Creates the <see cref="Codecs.PostingsReaderBase"/> for this + /// format. /// </summary> public abstract PostingsReaderBase PostingsReaderBase(SegmentReadState state); /// <summary> - /// Creates the <seealso cref="PostingsWriterBase"/> for this - /// format. + /// Creates the <see cref="Codecs.PostingsWriterBase"/> for this + /// format. /// </summary> public abstract PostingsWriterBase PostingsWriterBase(SegmentWriteState state); } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/PostingsConsumer.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/PostingsConsumer.cs b/src/Lucene.Net/Codecs/PostingsConsumer.cs index b8615a7..c4dedfc 100644 --- a/src/Lucene.Net/Codecs/PostingsConsumer.cs +++ b/src/Lucene.Net/Codecs/PostingsConsumer.cs @@ -29,29 +29,29 @@ namespace Lucene.Net.Codecs /// <summary> /// Abstract API that consumes postings for an individual term. - /// <p> + /// <para/> /// The lifecycle is: - /// <ol> - /// <li>PostingsConsumer is returned for each term by - /// <seealso cref="TermsConsumer#startTerm(BytesRef)"/>. - /// <li><seealso cref="#startDoc(int, int)"/> is called for each + /// <list type="number"> + /// <item><description>PostingsConsumer is returned for each term by + /// <see cref="TermsConsumer.StartTerm(BytesRef)"/>.</description></item> + /// <item><description><see cref="StartDoc(int, int)"/> is called for each /// document where the term occurs, specifying id - /// and term frequency for that document. - /// <li>If positions are enabled for the field, then - /// <seealso cref="#addPosition(int, BytesRef, int, int)"/> + /// and term frequency for that document.</description></item> + /// <item><description>If positions are enabled for the field, then + /// <see cref="AddPosition(int, BytesRef, int, int)"/> /// will be called for each occurrence in the - /// document. - /// <li><seealso cref="#finishDoc()"/> is called when the producer - /// is done adding positions to the document. - /// </ol> - /// + /// document.</description></item> + /// <item><description><see cref="FinishDoc()"/> is called when the producer + /// is done adding positions to the document.</description></item> + /// </list> + /// <para/> /// @lucene.experimental /// </summary> public abstract class PostingsConsumer { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal PostingsConsumer() { @@ -59,30 +59,30 @@ namespace Lucene.Net.Codecs /// <summary> /// Adds a new doc in this term. - /// <code>freq</code> will be -1 when term frequencies are omitted + /// <paramref name="freq"/> will be -1 when term frequencies are omitted /// for the field. /// </summary> public abstract void StartDoc(int docId, int freq); /// <summary> - /// Add a new position & payload, and start/end offset. A - /// null payload means no payload; a non-null payload with - /// zero length also means no payload. Caller may reuse - /// the <seealso cref="BytesRef"/> for the payload between calls - /// (method must fully consume the payload). <code>startOffset</code> - /// and <code>endOffset</code> will be -1 when offsets are not indexed. + /// Add a new position & payload, and start/end offset. A + /// <c>null</c> <paramref name="payload"/> means no payload; a non-<c>null</c> <paramref name="payload"/> with + /// zero length also means no payload. Caller may reuse + /// the <see cref="BytesRef"/> for the <paramref name="payload"/> between calls + /// (method must fully consume the payload). <paramref name="startOffset"/> + /// and <paramref name="endOffset"/> will be -1 when offsets are not indexed. /// </summary> public abstract void AddPosition(int position, BytesRef payload, int startOffset, int endOffset); /// <summary> - /// Called when we are done adding positions & payloads - /// for each doc. + /// Called when we are done adding positions & payloads + /// for each doc. /// </summary> public abstract void FinishDoc(); /// <summary> /// Default merge impl: append documents, mapping around - /// deletes + /// deletes. /// </summary> public virtual TermStats Merge(MergeState mergeState, IndexOptions indexOptions, DocsEnum postings, FixedBitSet visitedDocs) { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/PostingsFormat.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/PostingsFormat.cs b/src/Lucene.Net/Codecs/PostingsFormat.cs index bc34e65..2ea5dba 100644 --- a/src/Lucene.Net/Codecs/PostingsFormat.cs +++ b/src/Lucene.Net/Codecs/PostingsFormat.cs @@ -28,7 +28,7 @@ namespace Lucene.Net.Codecs /// Note, when extending this class, the name (<see cref="Name"/>) may /// written into the index in certain configurations. In order for the segment /// to be read, the name must resolve to your implementation via <see cref="ForName(string)"/>. - /// this method uses <see cref="IPostingsFormatFactory.GetPostingsFormat(string)"/> to resolve format names. + /// This method uses <see cref="IPostingsFormatFactory.GetPostingsFormat(string)"/> to resolve format names. /// <para/> /// If you implement your own format: /// <list type="number"> @@ -105,14 +105,14 @@ namespace Lucene.Net.Codecs /// (such as when using <see cref="PerField.PerFieldPostingsFormat"/>): in such configurations, /// for the segment to be read this class should be registered by subclassing <see cref="DefaultPostingsFormatFactory"/> and /// calling <see cref="DefaultPostingsFormatFactory.ScanForPostingsFormats(System.Reflection.Assembly)"/> in the class constructor. - /// The new <see cref="IPostingsFormatFactory"/> can be registered by calling <see cref="SetPostingsFormatFactory"/> at application startup.</summary> + /// The new <see cref="IPostingsFormatFactory"/> can be registered by calling <see cref="SetPostingsFormatFactory(IPostingsFormatFactory)"/> at application startup.</summary> protected PostingsFormat() { this.name = NamedServiceFactory<PostingsFormat>.GetServiceName(this.GetType()); } /// <summary> - /// Returns this posting format's name </summary> + /// Returns this posting format's name. </summary> public string Name { get @@ -122,7 +122,7 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Writes a new segment </summary> + /// Writes a new segment. </summary> public abstract FieldsConsumer FieldsConsumer(SegmentWriteState state); /// <summary> @@ -131,8 +131,8 @@ namespace Lucene.Net.Codecs /// use; else, those files may be deleted. /// Additionally, required files may be deleted during the execution of /// this call before there is a chance to open them. Under these - /// circumstances an IOException should be thrown by the implementation. - /// IOExceptions are expected and will automatically cause a retry of the + /// circumstances an <see cref="System.IO.IOException"/> should be thrown by the implementation. + /// <see cref="System.IO.IOException"/>s are expected and will automatically cause a retry of the /// segment opening logic with the newly revised segments. /// </summary> public abstract FieldsProducer FieldsProducer(SegmentReadState state); @@ -143,14 +143,14 @@ namespace Lucene.Net.Codecs } /// <summary> - /// looks up a format by name </summary> + /// Looks up a format by name. </summary> public static PostingsFormat ForName(string name) { return postingsFormatFactory.GetPostingsFormat(name); } /// <summary> - /// returns a list of all available format names </summary> + /// Returns a list of all available format names. </summary> public static ICollection<string> AvailablePostingsFormats() { if (postingsFormatFactory is IServiceListable) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/PostingsReaderBase.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/PostingsReaderBase.cs b/src/Lucene.Net/Codecs/PostingsReaderBase.cs index 8a5688b..38cdb48 100644 --- a/src/Lucene.Net/Codecs/PostingsReaderBase.cs +++ b/src/Lucene.Net/Codecs/PostingsReaderBase.cs @@ -29,14 +29,15 @@ namespace Lucene.Net.Codecs /// <summary> /// The core terms dictionaries (BlockTermsReader, - /// BlockTreeTermsReader) interact with a single instance - /// of this class to manage creation of <seealso cref="DocsEnum"/> and - /// <seealso cref="DocsAndPositionsEnum"/> instances. It provides an - /// IndexInput (termsIn) where this class may read any - /// previously stored data that it had written in its - /// corresponding <seealso cref="PostingsWriterBase"/> at indexing - /// time. - /// @lucene.experimental + /// <see cref="BlockTreeTermsReader"/>) interact with a single instance + /// of this class to manage creation of <see cref="DocsEnum"/> and + /// <see cref="DocsAndPositionsEnum"/> instances. It provides an + /// <see cref="IndexInput"/> (termsIn) where this class may read any + /// previously stored data that it had written in its + /// corresponding <see cref="PostingsWriterBase"/> at indexing + /// time. + /// <para/> + /// @lucene.experimental /// </summary> // TODO: find a better name; this defines the API that the @@ -46,7 +47,7 @@ namespace Lucene.Net.Codecs { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal PostingsReaderBase() { @@ -54,51 +55,58 @@ namespace Lucene.Net.Codecs /// <summary> /// Performs any initialization, such as reading and - /// verifying the header from the provided terms - /// dictionary <seealso cref="IndexInput"/>. + /// verifying the header from the provided terms + /// dictionary <see cref="IndexInput"/>. /// </summary> public abstract void Init(IndexInput termsIn); /// <summary> - /// Return a newly created empty TermState </summary> + /// Return a newly created empty <see cref="TermState"/>. </summary> public abstract BlockTermState NewTermState(); /// <summary> - /// Actually decode metadata for next term </summary> - /// <seealso cref= PostingsWriterBase#encodeTerm </seealso> + /// Actually decode metadata for next term. </summary> + /// <seealso cref="PostingsWriterBase.EncodeTerm(long[], Store.DataOutput, FieldInfo, BlockTermState, bool)"/> public abstract void DecodeTerm(long[] longs, DataInput @in, FieldInfo fieldInfo, BlockTermState state, bool absolute); /// <summary> /// Must fully consume state, since after this call that - /// TermState may be reused. + /// <see cref="TermState"/> may be reused. /// </summary> public abstract DocsEnum Docs(FieldInfo fieldInfo, BlockTermState state, IBits skipDocs, DocsEnum reuse, DocsFlags flags); /// <summary> /// Must fully consume state, since after this call that - /// TermState may be reused. + /// <see cref="TermState"/> may be reused. /// </summary> public abstract DocsAndPositionsEnum DocsAndPositions(FieldInfo fieldInfo, BlockTermState state, IBits skipDocs, DocsAndPositionsEnum reuse, DocsAndPositionsFlags flags); /// <summary> - /// Returns approximate RAM bytes used </summary> + /// Returns approximate RAM bytes used. </summary> public abstract long RamBytesUsed(); /// <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(); + /// <summary> + /// Disposes all resources used by this object. + /// </summary> public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } + /// <summary> + /// Implementations must override and should dispose all resources used by this instance. + /// </summary> protected abstract void Dispose(bool disposing); } } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/PostingsWriterBase.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/PostingsWriterBase.cs b/src/Lucene.Net/Codecs/PostingsWriterBase.cs index dfedbda..55b1e33 100644 --- a/src/Lucene.Net/Codecs/PostingsWriterBase.cs +++ b/src/Lucene.Net/Codecs/PostingsWriterBase.cs @@ -24,16 +24,17 @@ namespace Lucene.Net.Codecs using IndexOutput = Lucene.Net.Store.IndexOutput; /// <summary> - /// Extension of <seealso cref="PostingsConsumer"/> to support pluggable term dictionaries. - /// <p> - /// this class contains additional hooks to interact with the provided - /// term dictionaries such as <seealso cref="BlockTreeTermsWriter"/>. If you want + /// Extension of <see cref="PostingsConsumer"/> to support pluggable term dictionaries. + /// <para/> + /// This class contains additional hooks to interact with the provided + /// term dictionaries such as <see cref="BlockTreeTermsWriter"/>. If you want /// to re-use an existing implementation and are only interested in /// customizing the format of the postings list, extend this class /// instead. + /// <para/> + /// @lucene.experimental /// </summary> - /// <seealso cref= PostingsReaderBase - /// @lucene.experimental </seealso> + /// <seealso cref="PostingsReaderBase"/> // TODO: find a better name; this defines the API that the // terms dict impls use to talk to a postings impl. // TermsDict + PostingsReader/WriterBase == PostingsConsumer/Producer @@ -41,7 +42,7 @@ namespace Lucene.Net.Codecs { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal PostingsWriterBase() { @@ -49,58 +50,64 @@ namespace Lucene.Net.Codecs /// <summary> /// Called once after startup, before any terms have been - /// added. Implementations typically write a header to - /// the provided {@code termsOut}. + /// added. Implementations typically write a header to + /// the provided <paramref name="termsOut"/>. /// </summary> public abstract void Init(IndexOutput termsOut); /// <summary> - /// Return a newly created empty TermState </summary> + /// Return a newly created empty <see cref="Index.TermState"/> </summary> public abstract BlockTermState NewTermState(); /// <summary> - /// Start a new term. Note that a matching call to {@link - /// #finishTerm(BlockTermState)} is done, only if the term has at least one - /// document. + /// Start a new term. Note that a matching call to + /// <see cref="FinishTerm(BlockTermState)"/> is done, only if the term has at least one + /// document. /// </summary> public abstract void StartTerm(); /// <summary> - /// Finishes the current term. The provided {@link - /// BlockTermState} contains the term's summary statistics, - /// and will holds metadata from PBF when returned + /// Finishes the current term. The provided + /// <see cref="BlockTermState"/> contains the term's summary statistics, + /// and will holds metadata from PBF when returned. /// </summary> public abstract void FinishTerm(BlockTermState state); /// <summary> - /// Encode metadata as long[] and byte[]. {@code absolute} controls whether + /// Encode metadata as <see cref="T:long[]"/> and <see cref="T:byte[]"/>. <paramref name="absolute"/> controls whether /// current term is delta encoded according to latest term. - /// Usually elements in {@code longs} are file pointers, so each one always - /// increases when a new term is consumed. {@code out} is used to write generic + /// Usually elements in <paramref name="longs"/> are file pointers, so each one always + /// increases when a new term is consumed. <paramref name="out"/> is used to write generic /// bytes, which are not monotonic. - /// - /// NOTE: sometimes long[] might contain "don't care" values that are unused, e.g. + /// <para/> + /// NOTE: sometimes <see cref="T:long[]"/> might contain "don't care" values that are unused, e.g. /// the pointer to postings list may not be defined for some terms but is defined - /// for others, if it is designed to inline some postings data in term dictionary. + /// for others, if it is designed to inline some postings data in term dictionary. /// In this case, the postings writer should always use the last value, so that each - /// element in metadata long[] remains monotonic. + /// element in metadata <see cref="T:long[]"/> remains monotonic. /// </summary> public abstract void EncodeTerm(long[] longs, DataOutput @out, FieldInfo fieldInfo, BlockTermState state, bool absolute); /// <summary> /// Sets the current field for writing, and returns the - /// fixed length of long[] metadata (which is fixed per + /// fixed length of <see cref="T:long[]"/> metadata (which is fixed per /// field), called when the writing switches to another field. /// </summary> // TODO: better name? public abstract int SetField(FieldInfo fieldInfo); + /// <summary> + /// Disposes all resources used by this object. + /// </summary> public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } + /// <summary> + /// Implementations must override and should dispose all resources used by this instance. + /// </summary> protected abstract void Dispose(bool disposing); } } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/SegmentInfoFormat.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/SegmentInfoFormat.cs b/src/Lucene.Net/Codecs/SegmentInfoFormat.cs index 54f20a6..7e1b785 100644 --- a/src/Lucene.Net/Codecs/SegmentInfoFormat.cs +++ b/src/Lucene.Net/Codecs/SegmentInfoFormat.cs @@ -21,30 +21,30 @@ namespace Lucene.Net.Codecs /// <summary> /// Expert: Controls the format of the - /// <seealso cref="SegmentInfo"/> (segment metadata file). - /// <p> + /// <see cref="SegmentInfo"/> (segment metadata file). + /// <para/> + /// @lucene.experimental /// </summary> - /// <seealso cref= SegmentInfo - /// @lucene.experimental </seealso> + /// <seealso cref="SegmentInfo"/> public abstract class SegmentInfoFormat { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal SegmentInfoFormat() { } /// <summary> - /// Returns the <seealso cref="SegmentInfoReader"/> for reading - /// <seealso cref="SegmentInfo"/> instances. + /// Returns the <see cref="Codecs.SegmentInfoReader"/> for reading + /// <see cref="SegmentInfo"/> instances. /// </summary> public abstract SegmentInfoReader SegmentInfoReader { get; } /// <summary> - /// Returns the <seealso cref="SegmentInfoWriter"/> for writing - /// <seealso cref="SegmentInfo"/> instances. + /// Returns the <see cref="Codecs.SegmentInfoWriter"/> for writing + /// <see cref="SegmentInfo"/> instances. /// </summary> public abstract SegmentInfoWriter SegmentInfoWriter { get; } } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/SegmentInfoReader.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/SegmentInfoReader.cs b/src/Lucene.Net/Codecs/SegmentInfoReader.cs index afa8e4e..4e0a4ba 100644 --- a/src/Lucene.Net/Codecs/SegmentInfoReader.cs +++ b/src/Lucene.Net/Codecs/SegmentInfoReader.cs @@ -22,26 +22,27 @@ namespace Lucene.Net.Codecs using SegmentInfo = Lucene.Net.Index.SegmentInfo; /// <summary> - /// Specifies an API for classes that can read <seealso cref="SegmentInfo"/> information. + /// Specifies an API for classes that can read <see cref="SegmentInfo"/> information. + /// <para/> /// @lucene.experimental /// </summary> - public abstract class SegmentInfoReader { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal SegmentInfoReader() { } /// <summary> - /// Read <seealso cref="SegmentInfo"/> data from a directory. </summary> - /// <param name="directory"> directory to read from </param> - /// <param name="segmentName"> name of the segment to read </param> - /// <returns> infos instance to be populated with data </returns> - /// <exception cref="IOException"> If an I/O error occurs </exception> + /// Read <see cref="SegmentInfo"/> data from a directory. </summary> + /// <param name="directory"> Directory to read from. </param> + /// <param name="segmentName"> Name of the segment to read. </param> + /// <param name="context"> IO context. </param> + /// <returns> Infos instance to be populated with data. </returns> + /// <exception cref="System.IO.IOException"> If an I/O error occurs. </exception> public abstract SegmentInfo Read(Directory directory, string segmentName, IOContext context); } } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/SegmentInfoWriter.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/SegmentInfoWriter.cs b/src/Lucene.Net/Codecs/SegmentInfoWriter.cs index 2ba610a..8a73f8c 100644 --- a/src/Lucene.Net/Codecs/SegmentInfoWriter.cs +++ b/src/Lucene.Net/Codecs/SegmentInfoWriter.cs @@ -23,23 +23,23 @@ namespace Lucene.Net.Codecs using SegmentInfo = Lucene.Net.Index.SegmentInfo; /// <summary> - /// Specifies an API for classes that can write out <seealso cref="SegmentInfo"/> data. + /// Specifies an API for classes that can write out <see cref="SegmentInfo"/> data. + /// <para/> /// @lucene.experimental /// </summary> - public abstract class SegmentInfoWriter { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal SegmentInfoWriter() { } /// <summary> - /// Write <seealso cref="SegmentInfo"/> data. </summary> - /// <exception cref="IOException"> If an I/O error occurs </exception> + /// Write <see cref="SegmentInfo"/> data. </summary> + /// <exception cref="System.IO.IOException"> If an I/O error occurs. </exception> public abstract void Write(Directory dir, SegmentInfo info, FieldInfos fis, IOContext ioContext); } } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/StoredFieldsFormat.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/StoredFieldsFormat.cs b/src/Lucene.Net/Codecs/StoredFieldsFormat.cs index 8db0844..1e65f63 100644 --- a/src/Lucene.Net/Codecs/StoredFieldsFormat.cs +++ b/src/Lucene.Net/Codecs/StoredFieldsFormat.cs @@ -23,27 +23,27 @@ namespace Lucene.Net.Codecs using SegmentInfo = Lucene.Net.Index.SegmentInfo; /// <summary> - /// Controls the format of stored fields + /// Controls the format of stored fields. /// </summary> public abstract class StoredFieldsFormat { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal StoredFieldsFormat() { } /// <summary> - /// Returns a <seealso cref="StoredFieldsReader"/> to load stored - /// fields. + /// Returns a <see cref="StoredFieldsReader"/> to load stored + /// fields. /// </summary> public abstract StoredFieldsReader FieldsReader(Directory directory, SegmentInfo si, FieldInfos fn, IOContext context); /// <summary> - /// Returns a <seealso cref="StoredFieldsWriter"/> to write stored - /// fields. + /// Returns a <see cref="StoredFieldsWriter"/> to write stored + /// fields. /// </summary> public abstract StoredFieldsWriter FieldsWriter(Directory directory, SegmentInfo si, IOContext context); } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/StoredFieldsReader.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/StoredFieldsReader.cs b/src/Lucene.Net/Codecs/StoredFieldsReader.cs index 5a093b2..969f541 100644 --- a/src/Lucene.Net/Codecs/StoredFieldsReader.cs +++ b/src/Lucene.Net/Codecs/StoredFieldsReader.cs @@ -23,46 +23,54 @@ namespace Lucene.Net.Codecs /// <summary> /// Codec API for reading stored fields. - /// - /// You need to implement visitDocument(int, StoredFieldVisitor) to - /// read the stored fields for a document, implement clone( (creating - /// clones of any IndexInputs used, etc), and close() - /// + /// <para/> + /// You need to implement <see cref="VisitDocument(int, StoredFieldVisitor)"/> to + /// read the stored fields for a document, implement <see cref="Clone()"/> (creating + /// clones of any <see cref="Store.IndexInput"/>s used, etc), and <see cref="Dispose(bool)"/> + /// to cleanup any allocated resources. + /// <para/> /// @lucene.experimental /// </summary> public abstract class StoredFieldsReader : IDisposable { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal StoredFieldsReader() { } /// <summary> - /// Visit the stored fields for document <code>n</code> </summary> + /// Visit the stored fields for document <paramref name="n"/>. </summary> public abstract void VisitDocument(int n, StoredFieldVisitor visitor); public abstract object Clone(); + /// <summary> + /// Disposes all resources used by this object. + /// </summary> public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } + /// <summary> + /// Implementations must override and should dispose all resources used by this instance. + /// </summary> protected abstract void Dispose(bool disposing); /// <summary> - /// Returns approximate RAM bytes used </summary> + /// Returns approximate RAM bytes used. </summary> public abstract long RamBytesUsed(); /// <summary> /// Checks consistency of this reader. - /// + /// <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/a08ae945/src/Lucene.Net/Codecs/StoredFieldsWriter.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/StoredFieldsWriter.cs b/src/Lucene.Net/Codecs/StoredFieldsWriter.cs index 29ac364..15f7112 100644 --- a/src/Lucene.Net/Codecs/StoredFieldsWriter.cs +++ b/src/Lucene.Net/Codecs/StoredFieldsWriter.cs @@ -30,24 +30,24 @@ namespace Lucene.Net.Codecs /// <summary> /// Codec API for writing stored fields: - /// <p> - /// <ol> - /// <li>For every document, <seealso cref="#startDocument(int)"/> is called, - /// informing the Codec how many fields will be written. - /// <li><seealso cref="#writeField(FieldInfo, IndexableField)"/> is called for - /// each field in the document. - /// <li>After all documents have been written, <seealso cref="#finish(FieldInfos, int)"/> - /// is called for verification/sanity-checks. - /// <li>Finally the writer is closed (<seealso cref="#close()"/>) - /// </ol> - /// + /// <para/> + /// <list type="number"> + /// <item><description>For every document, <see cref="StartDocument(int)"/> is called, + /// informing the Codec how many fields will be written.</description></item> + /// <item><description><see cref="WriteField(FieldInfo, IIndexableField)"/> is called for + /// each field in the document.</description></item> + /// <item><description>After all documents have been written, <see cref="Finish(FieldInfos, int)"/> + /// is called for verification/sanity-checks.</description></item> + /// <item><description>Finally the writer is disposed (<see cref="Dispose(bool)"/>)</description></item> + /// </list> + /// <para/> /// @lucene.experimental /// </summary> public abstract class StoredFieldsWriter : IDisposable { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal StoredFieldsWriter() { @@ -55,10 +55,10 @@ namespace Lucene.Net.Codecs /// <summary> /// Called before writing the stored fields of the document. - /// <seealso cref="#writeField(FieldInfo, IndexableField)"/> will be called - /// <code>numStoredFields</code> times. Note that this is - /// called even if the document has no stored fields, in - /// this case <code>numStoredFields</code> will be zero. + /// <see cref="WriteField(FieldInfo, IIndexableField)"/> will be called + /// <paramref name="numStoredFields"/> times. Note that this is + /// called even if the document has no stored fields, in + /// this case <paramref name="numStoredFields"/> will be zero. /// </summary> public abstract void StartDocument(int numStoredFields); @@ -74,28 +74,28 @@ namespace Lucene.Net.Codecs /// <summary> /// Aborts writing entirely, implementation should remove - /// any partially-written files, etc. + /// any partially-written files, etc. /// </summary> public abstract void Abort(); /// <summary> - /// Called before <seealso cref="#close()"/>, passing in the number - /// of documents that were written. Note that this is - /// intentionally redundant (equivalent to the number of - /// calls to <seealso cref="#startDocument(int)"/>, but a Codec should - /// check that this is the case to detect the JRE bug described - /// in LUCENE-1282. + /// Called before <see cref="Dispose()"/>, passing in the number + /// of documents that were written. Note that this is + /// intentionally redundant (equivalent to the number of + /// calls to <see cref="StartDocument(int)"/>, but a <see cref="Codec"/> should + /// check that this is the case to detect the bug described + /// in LUCENE-1282. /// </summary> public abstract void Finish(FieldInfos fis, int numDocs); /// <summary> /// Merges in the stored fields from the readers in - /// <code>mergeState</code>. The default implementation skips - /// over deleted documents, and uses <seealso cref="#startDocument(int)"/>, - /// <seealso cref="#writeField(FieldInfo, IndexableField)"/>, and <seealso cref="#finish(FieldInfos, int)"/>, - /// returning the number of documents that were written. - /// Implementations can override this method for more sophisticated - /// merging (bulk-byte copying, etc). + /// <paramref name="mergeState"/>. The default implementation skips + /// over deleted documents, and uses <see cref="StartDocument(int)"/>, + /// <see cref="WriteField(FieldInfo, IIndexableField)"/>, and <see cref="Finish(FieldInfos, int)"/>, + /// returning the number of documents that were written. + /// Implementations can override this method for more sophisticated + /// merging (bulk-byte copying, etc). /// </summary> public virtual int Merge(MergeState mergeState) { @@ -128,7 +128,8 @@ namespace Lucene.Net.Codecs } /// <summary> - /// sugar method for startDocument() + writeField() for every stored field in the document </summary> + /// Sugar method for <see cref="StartDocument(int)"/> + <see cref="WriteField(FieldInfo, IIndexableField)"/> + /// for every stored field in the document. </summary> protected void AddDocument<T1>(IEnumerable<T1> doc, FieldInfos fieldInfos) where T1 : Lucene.Net.Index.IIndexableField { int storedCount = 0; @@ -153,12 +154,18 @@ namespace Lucene.Net.Codecs FinishDocument(); } + /// <summary> + /// Disposes all resources used by this object. + /// </summary> public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } + /// <summary> + /// Implementations must override and should dispose all resources used by this instance. + /// </summary> protected abstract void Dispose(bool disposing); } } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/TermStats.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/TermStats.cs b/src/Lucene.Net/Codecs/TermStats.cs index 9481a6c..013a21f 100644 --- a/src/Lucene.Net/Codecs/TermStats.cs +++ b/src/Lucene.Net/Codecs/TermStats.cs @@ -22,19 +22,19 @@ namespace Lucene.Net.Codecs /// <summary> /// Holder for per-term statistics. /// </summary> - /// <seealso cref= TermsEnum#docFreq </seealso> - /// <seealso cref= TermsEnum#totalTermFreq </seealso> + /// <seealso cref="Index.TermsEnum.DocFreq"/> + /// <seealso cref="Index.TermsEnum.TotalTermFreq"/> public class TermStats { /// <summary> /// How many documents have at least one occurrence of - /// this term. + /// this term. /// </summary> public int DocFreq { get; private set; } /// <summary> /// Total number of times this term occurs across all - /// documents in the field. + /// documents in the field. /// </summary> public long TotalTermFreq { get; private set; } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/TermVectorsFormat.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/TermVectorsFormat.cs b/src/Lucene.Net/Codecs/TermVectorsFormat.cs index 84cef97..025c2ba 100644 --- a/src/Lucene.Net/Codecs/TermVectorsFormat.cs +++ b/src/Lucene.Net/Codecs/TermVectorsFormat.cs @@ -23,27 +23,27 @@ namespace Lucene.Net.Codecs using SegmentInfo = Lucene.Net.Index.SegmentInfo; /// <summary> - /// Controls the format of term vectors + /// Controls the format of term vectors. /// </summary> public abstract class TermVectorsFormat { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal TermVectorsFormat() { } /// <summary> - /// Returns a <seealso cref="TermVectorsReader"/> to read term - /// vectors. + /// Returns a <see cref="TermVectorsReader"/> to read term + /// vectors. /// </summary> public abstract TermVectorsReader VectorsReader(Directory directory, SegmentInfo segmentInfo, FieldInfos fieldInfos, IOContext context); /// <summary> - /// Returns a <seealso cref="TermVectorsWriter"/> to write term - /// vectors. + /// Returns a <see cref="TermVectorsWriter"/> to write term + /// vectors. /// </summary> public abstract TermVectorsWriter VectorsWriter(Directory directory, SegmentInfo segmentInfo, IOContext context); } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/TermVectorsReader.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/TermVectorsReader.cs b/src/Lucene.Net/Codecs/TermVectorsReader.cs index c106b7b..1f5d0bd 100644 --- a/src/Lucene.Net/Codecs/TermVectorsReader.cs +++ b/src/Lucene.Net/Codecs/TermVectorsReader.cs @@ -25,52 +25,59 @@ namespace Lucene.Net.Codecs /// <summary> /// Codec API for reading term vectors: - /// + /// <para/> /// @lucene.experimental /// </summary> public abstract class TermVectorsReader : IDisposable { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal TermVectorsReader() { } /// <summary> - /// Returns term vectors for this document, or null if - /// term vectors were not indexed. If offsets are - /// available they are in an <seealso cref="OffsetAttribute"/> - /// available from the <seealso cref="DocsAndPositionsEnum"/>. + /// Returns term vectors for this document, or <c>null</c> if + /// term vectors were not indexed. If offsets are + /// available they are in an <see cref="OffsetAttribute"/> + /// available from the <see cref="DocsAndPositionsEnum"/>. /// </summary> public abstract Fields Get(int doc); /// <summary> - /// Returns approximate RAM bytes used </summary> + /// Returns approximate RAM bytes used. </summary> public abstract long RamBytesUsed(); /// <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(); /// <summary> /// Create a clone that one caller at a time may use to - /// read term vectors. + /// read term vectors. /// </summary> public abstract object Clone(); + /// <summary> + /// Disposes all resources used by this object. + /// </summary> public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } + /// <summary> + /// Implementations must override and should dispose all resources used by this instance. + /// </summary> protected abstract void Dispose(bool disposing); } } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/TermVectorsWriter.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/TermVectorsWriter.cs b/src/Lucene.Net/Codecs/TermVectorsWriter.cs index dd195c3..9d91956 100644 --- a/src/Lucene.Net/Codecs/TermVectorsWriter.cs +++ b/src/Lucene.Net/Codecs/TermVectorsWriter.cs @@ -37,31 +37,31 @@ namespace Lucene.Net.Codecs /// <summary> /// Codec API for writing term vectors: - /// <p> - /// <ol> - /// <li>For every document, <seealso cref="#startDocument(int)"/> is called, - /// informing the Codec how many fields will be written. - /// <li><seealso cref="#startField(FieldInfo, int, boolean, boolean, boolean)"/> is called for + /// <para/> + /// <list type="number"> + /// <item><description>For every document, <see cref="StartDocument(int)"/> is called, + /// informing the <see cref="Codec"/> how many fields will be written.</description></item> + /// <item><description><see cref="StartField(FieldInfo, int, bool, bool, bool)"/> is called for /// each field in the document, informing the codec how many terms /// will be written for that field, and whether or not positions, - /// offsets, or payloads are enabled. - /// <li>Within each field, <seealso cref="#startTerm(BytesRef, int)"/> is called - /// for each term. - /// <li>If offsets and/or positions are enabled, then - /// <seealso cref="#addPosition(int, int, int, BytesRef)"/> will be called for each term - /// occurrence. - /// <li>After all documents have been written, <seealso cref="#finish(FieldInfos, int)"/> - /// is called for verification/sanity-checks. - /// <li>Finally the writer is closed (<seealso cref="#close()"/>) - /// </ol> - /// + /// offsets, or payloads are enabled.</description></item> + /// <item><description>Within each field, <see cref="StartTerm(BytesRef, int)"/> is called + /// for each term.</description></item> + /// <item><description>If offsets and/or positions are enabled, then + /// <see cref="AddPosition(int, int, int, BytesRef)"/> will be called for each term + /// occurrence.</description></item> + /// <item><description>After all documents have been written, <see cref="Finish(FieldInfos, int)"/> + /// is called for verification/sanity-checks.</description></item> + /// <item><description>Finally the writer is disposed (<see cref="Dispose(bool)"/>)</description></item> + /// </list> + /// <para/> /// @lucene.experimental /// </summary> public abstract class TermVectorsWriter : IDisposable { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal TermVectorsWriter() { @@ -69,11 +69,11 @@ namespace Lucene.Net.Codecs /// <summary> /// Called before writing the term vectors of the document. - /// <seealso cref="#startField(FieldInfo, int, boolean, boolean, boolean)"/> will - /// be called <code>numVectorFields</code> times. Note that if term - /// vectors are enabled, this is called even if the document - /// has no vector fields, in this case <code>numVectorFields</code> - /// will be zero. + /// <see cref="StartField(FieldInfo, int, bool, bool, bool)"/> will + /// be called <paramref name="numVectorFields"/> times. Note that if term + /// vectors are enabled, this is called even if the document + /// has no vector fields, in this case <paramref name="numVectorFields"/> + /// will be zero. /// </summary> public abstract void StartDocument(int numVectorFields); @@ -85,7 +85,7 @@ namespace Lucene.Net.Codecs /// <summary> /// Called before writing the terms of the field. - /// <seealso cref="#startTerm(BytesRef, int)"/> will be called <code>numTerms</code> times. + /// <see cref="StartTerm(BytesRef, int)"/> will be called <paramref name="numTerms"/> times. /// </summary> public abstract void StartField(FieldInfo info, int numTerms, bool positions, bool offsets, bool payloads); @@ -96,10 +96,10 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Adds a term and its term frequency <code>freq</code>. + /// Adds a <paramref name="term"/> and its term frequency <paramref name="freq"/>. /// If this field has positions and/or offsets enabled, then - /// <seealso cref="#addPosition(int, int, int, BytesRef)"/> will be called - /// <code>freq</code> times respectively. + /// <see cref="AddPosition(int, int, int, BytesRef)"/> will be called + /// <paramref name="freq"/> times respectively. /// </summary> public abstract void StartTerm(BytesRef term, int freq); @@ -110,36 +110,37 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Adds a term position and offsets </summary> + /// Adds a term <paramref name="position"/> and offsets. </summary> public abstract void AddPosition(int position, int startOffset, int endOffset, BytesRef payload); /// <summary> /// Aborts writing entirely, implementation should remove - /// any partially-written files, etc. + /// any partially-written files, etc. /// </summary> public abstract void Abort(); /// <summary> - /// Called before <seealso cref="#close()"/>, passing in the number - /// of documents that were written. Note that this is - /// intentionally redundant (equivalent to the number of - /// calls to <seealso cref="#startDocument(int)"/>, but a Codec should - /// check that this is the case to detect the JRE bug described - /// in LUCENE-1282. + /// Called before <see cref="Dispose(bool)"/>, passing in the number + /// of documents that were written. Note that this is + /// intentionally redundant (equivalent to the number of + /// calls to <see cref="StartDocument(int)"/>, but a <see cref="Codec"/> should + /// check that this is the case to detect the bug described + /// in LUCENE-1282. /// </summary> public abstract void Finish(FieldInfos fis, int numDocs); /// <summary> - /// Called by IndexWriter when writing new segments. - /// <p> - /// this is an expert API that allows the codec to consume + /// Called by <see cref="Index.IndexWriter"/> when writing new segments. + /// <para/> + /// This is an expert API that allows the codec to consume /// positions and offsets directly from the indexer. - /// <p> - /// The default implementation calls <seealso cref="#addPosition(int, int, int, BytesRef)"/>, + /// <para/> + /// The default implementation calls <see cref="AddPosition(int, int, int, BytesRef)"/>, /// but subclasses can override this if they want to efficiently write /// all the positions, then all the offsets, for example. - /// <p> + /// <para/> /// NOTE: this API is extremely expert and subject to change or removal!!! + /// <para/> /// @lucene.internal /// </summary> // TODO: we should probably nuke this and make a more efficient 4.x format @@ -206,14 +207,14 @@ namespace Lucene.Net.Codecs /// <summary> /// Merges in the term vectors from the readers in - /// <code>mergeState</code>. The default implementation skips - /// over deleted documents, and uses <seealso cref="#startDocument(int)"/>, - /// <seealso cref="#startField(FieldInfo, int, boolean, boolean, boolean)"/>, - /// <seealso cref="#startTerm(BytesRef, int)"/>, <seealso cref="#addPosition(int, int, int, BytesRef)"/>, - /// and <seealso cref="#finish(FieldInfos, int)"/>, - /// returning the number of documents that were written. - /// Implementations can override this method for more sophisticated - /// merging (bulk-byte copying, etc). + /// <paramref name="mergeState"/>. The default implementation skips + /// over deleted documents, and uses <see cref="StartDocument(int)"/>, + /// <see cref="StartField(FieldInfo, int, bool, bool, bool)"/>, + /// <see cref="StartTerm(BytesRef, int)"/>, <see cref="AddPosition(int, int, int, BytesRef)"/>, + /// and <see cref="Finish(FieldInfos, int)"/>, + /// returning the number of documents that were written. + /// Implementations can override this method for more sophisticated + /// merging (bulk-byte copying, etc). /// </summary> public virtual int Merge(MergeState mergeState) { @@ -245,7 +246,7 @@ namespace Lucene.Net.Codecs /// <summary> /// Safe (but, slowish) default method to write every - /// vector field in the document. + /// vector field in the document. /// </summary> protected void AddAllDocVectors(Fields vectors, MergeState mergeState) { @@ -350,17 +351,23 @@ namespace Lucene.Net.Codecs } /// <summary> - /// Return the BytesRef Comparer used to sort terms - /// before feeding to this API. + /// Return the <see cref="T:IComparer{BytesRef}"/> used to sort terms + /// before feeding to this API. /// </summary> public abstract IComparer<BytesRef> Comparer { get; } + /// <summary> + /// Disposes all resources used by this object. + /// </summary> public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } + /// <summary> + /// Implementations must override and should dispose all resources used by this instance. + /// </summary> protected abstract void Dispose(bool disposing); } } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a08ae945/src/Lucene.Net/Codecs/TermsConsumer.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Codecs/TermsConsumer.cs b/src/Lucene.Net/Codecs/TermsConsumer.cs index ca896bf..2789ef1 100644 --- a/src/Lucene.Net/Codecs/TermsConsumer.cs +++ b/src/Lucene.Net/Codecs/TermsConsumer.cs @@ -34,29 +34,29 @@ namespace Lucene.Net.Codecs /// <summary> /// Abstract API that consumes terms for an individual field. - /// <p> + /// <para/> /// The lifecycle is: - /// <ol> - /// <li>TermsConsumer is returned for each field - /// by <seealso cref="FieldsConsumer#addField(FieldInfo)"/>. - /// <li>TermsConsumer returns a <seealso cref="PostingsConsumer"/> for - /// each term in <seealso cref="#startTerm(BytesRef)"/>. - /// <li>When the producer (e.g. IndexWriter) + /// <list type="number"> + /// <item><description>TermsConsumer is returned for each field + /// by <see cref="FieldsConsumer.AddField(FieldInfo)"/>.</description></item> + /// <item><description>TermsConsumer returns a <see cref="PostingsConsumer"/> for + /// each term in <see cref="StartTerm(BytesRef)"/>.</description></item> + /// <item><description>When the producer (e.g. IndexWriter) /// is done adding documents for the term, it calls - /// <seealso cref="#finishTerm(BytesRef, TermStats)"/>, passing in - /// the accumulated term statistics. - /// <li>Producer calls <seealso cref="#finish(long, long, int)"/> with + /// <see cref="FinishTerm(BytesRef, TermStats)"/>, passing in + /// the accumulated term statistics.</description></item> + /// <item><description>Producer calls <see cref="Finish(long, long, int)"/> with /// the accumulated collection statistics when it is finished - /// adding terms to the field. - /// </ol> - /// + /// adding terms to the field.</description></item> + /// </list> + /// <para/> /// @lucene.experimental /// </summary> public abstract class TermsConsumer { /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected internal TermsConsumer() { @@ -64,28 +64,28 @@ namespace Lucene.Net.Codecs /// <summary> /// Starts a new term in this field; this may be called - /// with no corresponding call to finish if the term had - /// no docs. + /// with no corresponding call to finish if the term had + /// no docs. /// </summary> public abstract PostingsConsumer StartTerm(BytesRef text); /// <summary> - /// Finishes the current term; numDocs must be > 0. - /// <code>stats.totalTermFreq</code> will be -1 when term - /// frequencies are omitted for the field. + /// Finishes the current term; numDocs must be > 0. + /// <c>stats.TotalTermFreq</c> will be -1 when term + /// frequencies are omitted for the field. /// </summary> public abstract void FinishTerm(BytesRef text, TermStats stats); /// <summary> /// Called when we are done adding terms to this field. - /// <code>sumTotalTermFreq</code> will be -1 when term - /// frequencies are omitted for the field. + /// <paramref name="sumTotalTermFreq"/> will be -1 when term + /// frequencies are omitted for the field. /// </summary> public abstract void Finish(long sumTotalTermFreq, long sumDocFreq, int docCount); /// <summary> - /// Return the BytesRef Comparer used to sort terms - /// before feeding to this API. + /// Gets the <see cref="T:IComparer{BytesRef}"/> used to sort terms + /// before feeding to this API. /// </summary> public abstract IComparer<BytesRef> Comparer { get; } @@ -94,7 +94,7 @@ namespace Lucene.Net.Codecs private MappingMultiDocsAndPositionsEnum postingsEnum; /// <summary> - /// Default merge impl </summary> + /// Default merge impl. </summary> public virtual void Merge(MergeState mergeState, IndexOptions indexOptions, TermsEnum termsEnum) { BytesRef term;
