Lucene.Net.Index: Fixed documentation comments for types starting with I-L
Project: http://git-wip-us.apache.org/repos/asf/lucenenet/repo Commit: http://git-wip-us.apache.org/repos/asf/lucenenet/commit/530d26bb Tree: http://git-wip-us.apache.org/repos/asf/lucenenet/tree/530d26bb Diff: http://git-wip-us.apache.org/repos/asf/lucenenet/diff/530d26bb Branch: refs/heads/master Commit: 530d26bb37d6c79f9bda4d2d12323e2fb782fc58 Parents: 6038504 Author: Shad Storhaug <[email protected]> Authored: Mon May 1 01:43:08 2017 +0700 Committer: Shad Storhaug <[email protected]> Committed: Mon May 1 04:48:39 2017 +0700 ---------------------------------------------------------------------- CONTRIBUTING.md | 2 +- src/Lucene.Net/Index/IndexCommit.cs | 52 +++---- src/Lucene.Net/Index/IndexDeletionPolicy.cs | 72 +++++----- src/Lucene.Net/Index/IndexFileDeleter.cs | 143 ++++++++++--------- src/Lucene.Net/Index/IndexFileNames.cs | 45 +++--- .../Index/IndexFormatTooNewException.cs | 30 ++-- .../Index/IndexFormatTooOldException.cs | 50 +++---- src/Lucene.Net/Index/IndexNotFoundException.cs | 6 +- src/Lucene.Net/Index/IndexReaderContext.cs | 20 +-- src/Lucene.Net/Index/IndexUpgrader.cs | 48 ++++--- src/Lucene.Net/Index/IndexWriterConfig.cs | 2 +- src/Lucene.Net/Index/IndexableField.cs | 42 +++--- src/Lucene.Net/Index/IndexableFieldType.cs | 51 +++---- .../Index/KeepOnlyLastCommitDeletionPolicy.cs | 4 +- src/Lucene.Net/Index/LogByteSizeMergePolicy.cs | 51 +++---- src/Lucene.Net/Index/LogDocMergePolicy.cs | 13 +- src/Lucene.Net/Index/LogMergePolicy.cs | 124 ++++++++-------- 17 files changed, 386 insertions(+), 369 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/CONTRIBUTING.md ---------------------------------------------------------------------- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 713aa1a..be00288 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. Index (namespace) (Except for types starting with letter A-F, IndexWriter, IndexWriterConfig, IndexReader, LiveIndexWriterConfig, and TieredMergePolicy) + 2. Index (namespace) (Except for types starting with letter A-L and TieredMergePolicy) 3. Search (namespace) 4. Support (namespace) 5. Util (namespace) (Except for Util.Fst) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/IndexCommit.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/IndexCommit.cs b/src/Lucene.Net/Index/IndexCommit.cs index 24fab91..327afdc 100644 --- a/src/Lucene.Net/Index/IndexCommit.cs +++ b/src/Lucene.Net/Index/IndexCommit.cs @@ -23,19 +23,19 @@ namespace Lucene.Net.Index using Directory = Lucene.Net.Store.Directory; /// <summary> - /// <p>Expert: represents a single commit into an index as seen by the - /// <seealso cref="IndexDeletionPolicy"/> or <seealso cref="IndexReader"/>.</p> + /// <para>Expert: represents a single commit into an index as seen by the + /// <see cref="IndexDeletionPolicy"/> or <see cref="IndexReader"/>.</para> /// - /// <p> Changes to the content of an index are made visible + /// <para> Changes to the content of an index are made visible /// only after the writer who made that change commits by /// writing a new segments file - /// (<code>segments_N</code>). this point in time, when the + /// (<c>segments_N</c>). This point in time, when the /// action of writing of a new segments file to the directory - /// is completed, is an index commit.</p> + /// is completed, is an index commit.</para> /// - /// <p>Each index commit point has a unique segments file + /// <para>Each index commit point has a unique segments file /// associated with it. The segments file associated with a - /// later index commit point would have a larger N.</p> + /// later index commit point would have a larger N.</para> /// /// @lucene.experimental /// </summary> @@ -45,7 +45,7 @@ namespace Lucene.Net.Index public abstract class IndexCommit : IComparable<IndexCommit> { /// <summary> - /// Get the segments file (<code>segments_N</code>) associated + /// Get the segments file (<c>segments_N</c>) associated /// with this commit point. /// </summary> public abstract string SegmentsFileName { get; } @@ -56,28 +56,28 @@ namespace Lucene.Net.Index public abstract ICollection<string> FileNames { get; } /// <summary> - /// Returns the <seealso cref="Directory"/> for the index. + /// Returns the <see cref="Store.Directory"/> for the index. /// </summary> public abstract Directory Directory { get; } /// <summary> - /// Delete this commit point. this only applies when using - /// the commit point in the context of IndexWriter's - /// IndexDeletionPolicy. - /// <p> + /// Delete this commit point. This only applies when using + /// the commit point in the context of <see cref="IndexWriter"/>'s + /// <see cref="IndexDeletionPolicy"/>. + /// <para/> /// Upon calling this, the writer is notified that this commit /// point should be deleted. - /// <p> - /// Decision that a commit-point should be deleted is taken by the <seealso cref="IndexDeletionPolicy"/> in effect - /// and therefore this should only be called by its <seealso cref="IndexDeletionPolicy#onInit onInit()"/> or - /// <seealso cref="IndexDeletionPolicy#onCommit onCommit()"/> methods. + /// <para/> + /// Decision that a commit-point should be deleted is taken by the <see cref="IndexDeletionPolicy"/> in effect + /// and therefore this should only be called by its <see cref="IndexDeletionPolicy.OnInit{T}(IList{T})"/> or + /// <see cref="IndexDeletionPolicy.OnCommit{T}(IList{T})"/> methods. /// </summary> public abstract void Delete(); /// <summary> - /// Returns true if this commit should be deleted; this is - /// only used by <seealso cref="IndexWriter"/> after invoking the - /// <seealso cref="IndexDeletionPolicy"/>. + /// Returns <c>true</c> if this commit should be deleted; this is + /// only used by <see cref="IndexWriter"/> after invoking the + /// <see cref="IndexDeletionPolicy"/>. /// </summary> public abstract bool IsDeleted { get; } @@ -87,14 +87,14 @@ namespace Lucene.Net.Index /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> protected IndexCommit() { } /// <summary> - /// Two IndexCommits are equal if both their Directory and versions are equal. </summary> + /// Two IndexCommits are equal if both their <see cref="Store.Directory"/> and versions are equal. </summary> public override bool Equals(object other) { if (other is IndexCommit) @@ -115,14 +115,14 @@ namespace Lucene.Net.Index /// <summary> /// Returns the generation (the _N in segments_N) for this - /// IndexCommit + /// <see cref="IndexCommit"/> /// </summary> public abstract long Generation { get; } /// <summary> - /// Returns userData, previously passed to {@link - /// IndexWriter#setCommitData(Map)} for this commit. Map is - /// String -> String. + /// Returns userData, previously passed to + /// <see cref="IndexWriter.SetCommitData(IDictionary{string, string})"/>} for this commit. + /// The dictionary is <see cref="string"/> -> <see cref="string"/>. /// </summary> public abstract IDictionary<string, string> UserData { get; } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/IndexDeletionPolicy.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/IndexDeletionPolicy.cs b/src/Lucene.Net/Index/IndexDeletionPolicy.cs index d534cdd..2c00bb7 100644 --- a/src/Lucene.Net/Index/IndexDeletionPolicy.cs +++ b/src/Lucene.Net/Index/IndexDeletionPolicy.cs @@ -21,18 +21,18 @@ namespace Lucene.Net.Index */ /// <summary> - /// <p>Expert: policy for deletion of stale <seealso cref="IndexCommit index commits"/>. + /// <para>Expert: policy for deletion of stale <see cref="IndexCommit"/>s.</para> /// - /// <p>Implement this interface, and pass it to one - /// of the <seealso cref="IndexWriter"/> or <seealso cref="IndexReader"/> + /// <para>Implement this interface, and pass it to one + /// of the <see cref="IndexWriter"/> or <see cref="IndexReader"/> /// constructors, to customize when older - /// <seealso cref="IndexCommit point-in-time commits"/> + /// point-in-time commits (<see cref="IndexCommit"/>) /// are deleted from the index directory. The default deletion policy - /// is <seealso cref="KeepOnlyLastCommitDeletionPolicy"/>, which always + /// is <see cref="KeepOnlyLastCommitDeletionPolicy"/>, which always /// removes old commits as soon as a new commit is done (this - /// matches the behavior before 2.2).</p> + /// matches the behavior before 2.2).</para> /// - /// <p>One expected use case for this (and the reason why it + /// <para>One expected use case for this (and the reason why it /// was first created) is to work around problems with an /// index directory accessed via filesystems like NFS because /// NFS does not provide the "delete on last close" semantics @@ -40,16 +40,16 @@ namespace Lucene.Net.Index /// By implementing a custom deletion policy, such as "a /// commit is only removed once it has been stale for more /// than X minutes", you can give your readers time to - /// refresh to the new commit before <seealso cref="IndexWriter"/> + /// refresh to the new commit before <see cref="IndexWriter"/> /// removes the old commits. Note that doing so will /// increase the storage requirements of the index. See <a /// target="top" /// href="http://issues.apache.org/jira/browse/LUCENE-710";>LUCENE-710</a> - /// for details.</p> + /// for details.</para> /// - /// <p>Implementers of sub-classes should make sure that <seealso cref="#clone()"/> - /// returns an independent instance able to work with any other <seealso cref="IndexWriter"/> - /// or <seealso cref="Directory"/> instance.</p> + /// <para>Implementers of sub-classes should make sure that <see cref="Clone()"/> + /// returns an independent instance able to work with any other <see cref="IndexWriter"/> + /// or <see cref="Store.Directory"/> instance.</para> /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -63,49 +63,49 @@ namespace Lucene.Net.Index } /// <summary> - /// <p>this is called once when a writer is first + /// <para>this is called once when a writer is first /// instantiated to give the policy a chance to remove old - /// commit points.</p> + /// commit points.</para> /// - /// <p>The writer locates all index commits present in the + /// <para>The writer locates all index commits present in the /// index directory and calls this method. The policy may /// choose to delete some of the commit points, doing so by /// calling method <seealso cref="IndexCommit#delete delete()"/> - /// of <seealso cref="IndexCommit"/>.</p> + /// of <seealso cref="IndexCommit"/>.</para> /// - /// <p><u>Note:</u> the last CommitPoint is the most recent one, + /// <para><u>Note:</u> the last CommitPoint is the most recent one, /// i.e. the "front index state". Be careful not to delete it, /// unless you know for sure what you are doing, and unless - /// you can afford to lose the index content while doing that. + /// you can afford to lose the index content while doing that.</para> /// </summary> - /// <param name="commits"> List of current - /// <seealso cref="IndexCommit point-in-time commits"/>, - /// sorted by age (the 0th one is the oldest commit). - /// Note that for a new index this method is invoked with - /// an empty list. </param> + /// <param name="commits"> List of current point-in-time commits + /// (<see cref="IndexCommit"/>), + /// sorted by age (the 0th one is the oldest commit). + /// Note that for a new index this method is invoked with + /// an empty list. </param> public abstract void OnInit<T>(IList<T> commits) where T : IndexCommit; /// <summary> - /// <p>this is called each time the writer completed a commit. + /// <para>this is called each time the writer completed a commit. /// this gives the policy a chance to remove old commit points - /// with each commit.</p> + /// with each commit.</para> /// - /// <p>The policy may now choose to delete old commit points - /// by calling method <seealso cref="IndexCommit#delete delete()"/> - /// of <seealso cref="IndexCommit"/>.</p> + /// <para>The policy may now choose to delete old commit points + /// by calling method <see cref="IndexCommit.Delete()"/> + /// of <see cref="IndexCommit"/>.</para> /// - /// <p>this method is only called when {@link - /// IndexWriter#commit} or <seealso cref="IndexWriter#close"/> is - /// called, or possibly not at all if the {@link - /// IndexWriter#rollback} is called. + /// <para>This method is only called when + /// <see cref="IndexWriter.Commit()"/>} or <see cref="IndexWriter.Dispose()"/> is + /// called, or possibly not at all if the + /// <see cref="IndexWriter.Rollback()"/>} method is called.</para> /// - /// <p><u>Note:</u> the last CommitPoint is the most recent one, + /// <para><u>Note:</u> the last CommitPoint is the most recent one, /// i.e. the "front index state". Be careful not to delete it, /// unless you know for sure what you are doing, and unless - /// you can afford to lose the index content while doing that. + /// you can afford to lose the index content while doing that.</para> /// </summary> - /// <param name="commits"> List of <seealso cref="IndexCommit"/>, - /// sorted by age (the 0th one is the oldest commit). </param> + /// <param name="commits"> List of <see cref="IndexCommit"/>s, + /// sorted by age (the 0th one is the oldest commit). </param> public abstract void OnCommit<T>(IList<T> commits) where T : IndexCommit; public virtual object Clone() http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/IndexFileDeleter.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/IndexFileDeleter.cs b/src/Lucene.Net/Index/IndexFileDeleter.cs index 53ee959..fd1d414 100644 --- a/src/Lucene.Net/Index/IndexFileDeleter.cs +++ b/src/Lucene.Net/Index/IndexFileDeleter.cs @@ -30,69 +30,78 @@ namespace Lucene.Net.Index using Directory = Lucene.Net.Store.Directory; using InfoStream = Lucene.Net.Util.InfoStream; - /* - * this class keeps track of each SegmentInfos instance that - * is still "live", either because it corresponds to a - * segments_N file in the Directory (a "commit", i.e. a - * committed SegmentInfos) or because it's an in-memory - * SegmentInfos that a writer is actively updating but has - * not yet committed. this class uses simple reference - * counting to map the live SegmentInfos instances to - * individual files in the Directory. - * - * The same directory file may be referenced by more than - * one IndexCommit, i.e. more than one SegmentInfos. - * Therefore we count how many commits reference each file. - * When all the commits referencing a certain file have been - * deleted, the refcount for that file becomes zero, and the - * file is deleted. - * - * A separate deletion policy interface - * (IndexDeletionPolicy) is consulted on creation (onInit) - * and once per commit (onCommit), to decide when a commit - * should be removed. - * - * It is the business of the IndexDeletionPolicy to choose - * when to delete commit points. The actual mechanics of - * file deletion, retrying, etc, derived from the deletion - * of commit points is the business of the IndexFileDeleter. - * - * The current default deletion policy is {@link - * KeepOnlyLastCommitDeletionPolicy}, which removes all - * prior commits when a new commit has completed. this - * matches the behavior before 2.2. - * - * Note that you must hold the write.lock before - * instantiating this class. It opens segments_N file(s) - * directly with no retry logic. - */ + /// <summary> + /// This class keeps track of each SegmentInfos instance that + /// is still "live", either because it corresponds to a + /// segments_N file in the <see cref="Directory"/> (a "commit", i.e. a + /// committed <see cref="SegmentInfos"/>) or because it's an in-memory + /// <see cref="SegmentInfos"/> that a writer is actively updating but has + /// not yet committed. This class uses simple reference + /// counting to map the live <see cref="SegmentInfos"/> instances to + /// individual files in the <see cref="Directory"/>. + /// <para/> + /// The same directory file may be referenced by more than + /// one <see cref="IndexCommit"/>, i.e. more than one <see cref="SegmentInfos"/>. + /// Therefore we count how many commits reference each file. + /// When all the commits referencing a certain file have been + /// deleted, the refcount for that file becomes zero, and the + /// file is deleted. + /// <para/> + /// A separate deletion policy interface + /// (<see cref="IndexDeletionPolicy"/>) is consulted on creation (OnInit) + /// and once per commit (OnCommit), to decide when a commit + /// should be removed. + /// <para/> + /// It is the business of the <see cref="IndexDeletionPolicy"/> to choose + /// when to delete commit points. The actual mechanics of + /// file deletion, retrying, etc, derived from the deletion + /// of commit points is the business of the <see cref="IndexFileDeleter"/>. + /// <para/> + /// The current default deletion policy is + /// <see cref="KeepOnlyLastCommitDeletionPolicy"/>, which removes all + /// prior commits when a new commit has completed. This + /// matches the behavior before 2.2. + /// <para/> + /// Note that you must hold the <c>write.lock</c> before + /// instantiating this class. It opens segments_N file(s) + /// directly with no retry logic. + /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif internal sealed class IndexFileDeleter : IDisposable { - /* Files that we tried to delete but failed (likely - * because they are open and we are running on Windows), - * so we will retry them again later: */ + /// <summary> + /// Files that we tried to delete but failed (likely + /// because they are open and we are running on Windows), + /// so we will retry them again later: + /// </summary> private IList<string> deletable; - /* Reference count for all files in the index. - * Counts how many existing commits reference a file. - **/ + /// <summary> + /// Reference count for all files in the index. + /// Counts how many existing commits reference a file. + /// </summary> private IDictionary<string, RefCount> refCounts = new Dictionary<string, RefCount>(); - /* Holds all commits (segments_N) currently in the index. - * this will have just 1 commit if you are using the - * default delete policy (KeepOnlyLastCommitDeletionPolicy). - * Other policies may leave commit points live for longer - * in which case this list would be longer than 1: */ + /// <summary> + /// Holds all commits (segments_N) currently in the index. + /// this will have just 1 commit if you are using the + /// default delete policy (KeepOnlyLastCommitDeletionPolicy). + /// Other policies may leave commit points live for longer + /// in which case this list would be longer than 1: + /// </summary> private IList<CommitPoint> commits = new List<CommitPoint>(); - /* Holds files we had incref'd from the previous - * non-commit checkpoint: */ + /// <summary> + /// Holds files we had incref'd from the previous + /// non-commit checkpoint: + /// </summary> private readonly List<string> lastFiles = new List<string>(); - /* Commits that the IndexDeletionPolicy have decided to delete: */ + /// <summary> + /// Commits that the IndexDeletionPolicy have decided to delete: + /// </summary> private IList<CommitPoint> commitsToDelete = new List<CommitPoint>(); private readonly InfoStream infoStream; @@ -104,7 +113,7 @@ namespace Lucene.Net.Index /// <summary> /// Change to true to see details of reference counts when - /// infoStream is enabled + /// infoStream is enabled /// </summary> public static bool VERBOSE_REF_COUNTS = false; @@ -120,7 +129,7 @@ namespace Lucene.Net.Index /// <summary> /// Initialize the deleter: find all previous commits in - /// the Directory, incref the files they reference, call + /// the <see cref="Directory"/>, incref the files they reference, call /// the policy to let it delete commits. this will remove /// any files not referenced by any of the commits. </summary> /// <exception cref="IOException"> if there is a low-level IO error </exception> @@ -402,7 +411,7 @@ namespace Lucene.Net.Index /// Writer calls this when it has hit an error and had to /// roll back, to tell us that there may now be /// unreferenced files in the filesystem. So we re-list - /// the filesystem and delete such files. If segmentName + /// the filesystem and delete such files. If <paramref name="segmentName"/> /// is non-null, we will only delete files corresponding to /// that segment. /// </summary> @@ -469,12 +478,12 @@ namespace Lucene.Net.Index } /// <summary> - /// Revisits the <seealso cref="IndexDeletionPolicy"/> by calling its - /// <seealso cref="IndexDeletionPolicy#onCommit(List)"/> again with the known commits. + /// Revisits the <see cref="IndexDeletionPolicy"/> by calling its + /// <see cref="IndexDeletionPolicy.OnCommit{T}(IList{T})"/> again with the known commits. /// this is useful in cases where a deletion policy which holds onto index /// commits is used. The application may know that some commits are not held by /// the deletion policy anymore and call - /// <seealso cref="IndexWriter#deleteUnusedFiles()"/>, which will attempt to delete the + /// <see cref="IndexWriter.DeleteUnusedFiles()"/>, which will attempt to delete the /// unused commits again. /// </summary> internal void RevisitPolicy() @@ -512,21 +521,21 @@ namespace Lucene.Net.Index } /// <summary> - /// For definition of "check point" see IndexWriter comments: + /// For definition of "check point" see <see cref="IndexWriter"/> comments: /// "Clarification: Check Points (and commits)". - /// + /// <para/> /// Writer calls this when it has made a "consistent /// change" to the index, meaning new files are written to - /// the index and the in-memory SegmentInfos have been + /// the index and the in-memory <see cref="SegmentInfos"/> have been /// modified to point to those files. - /// - /// this may or may not be a commit (segments_N may or may + /// <para/> + /// This may or may not be a commit (segments_N may or may /// not have been written). - /// + /// <para/> /// We simply incref the files referenced by the new - /// SegmentInfos and decref the files we had previously + /// <see cref="SegmentInfos"/> and decref the files we had previously /// seen (if any). - /// + /// <para/> /// If this is a commit, we also call the policy to give it /// a chance to remove other commits. If any commits are /// removed, we decref their files as well. @@ -689,7 +698,7 @@ namespace Lucene.Net.Index /// <summary> /// Deletes the specified files, but only if they are new - /// (have not yet been incref'd). + /// (have not yet been incref'd). /// </summary> internal void DeleteNewFiles(ICollection<string> files) { @@ -790,7 +799,7 @@ namespace Lucene.Net.Index } /// <summary> - /// Holds details for each commit point. this class is + /// Holds details for each commit point. This class is /// also passed to the deletion policy. Note: this class /// has a natural ordering that is inconsistent with /// equals. @@ -874,7 +883,7 @@ namespace Lucene.Net.Index } /// <summary> - /// Called only be the deletion policy, to remove this + /// Called only by the deletion policy, to remove this /// commit point from the index. /// </summary> public override void Delete() http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/IndexFileNames.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/IndexFileNames.cs b/src/Lucene.Net/Index/IndexFileNames.cs index 7255e9d..f67c023 100644 --- a/src/Lucene.Net/Index/IndexFileNames.cs +++ b/src/Lucene.Net/Index/IndexFileNames.cs @@ -26,18 +26,18 @@ namespace Lucene.Net.Index // TODO: put all files under codec and remove all the static extensions here /// <summary> - /// this class contains useful constants representing filenames and extensions + /// This class contains useful constants representing filenames and extensions /// used by lucene, as well as convenience methods for querying whether a file - /// name matches an extension ({@link #matchesExtension(String, String) - /// matchesExtension}), as well as generating file names from a segment name, - /// generation and extension ( - /// <seealso cref="#fileNameFromGeneration(String, String, long) fileNameFromGeneration"/>, - /// <seealso cref="#segmentFileName(String, String, String) segmentFileName"/>). + /// name matches an extension (<see cref="MatchesExtension(string, string)"/>), + /// as well as generating file names from a segment name, + /// generation and extension + /// (<see cref="FileNameFromGeneration(string, string, long)"/>, + /// <see cref="SegmentFileName(string, string, string)"/>). /// - /// <p><b>NOTE</b>: extensions used by codecs are not - /// listed here. You must interact with the <seealso cref="Codec"/> + /// <para/><b>NOTE</b>: extensions used by codecs are not + /// listed here. You must interact with the <see cref="Codecs.Codec"/> /// directly. - /// + /// <para/> /// @lucene.internal /// </summary> #if FEATURE_SERIALIZABLE @@ -72,10 +72,10 @@ namespace Lucene.Net.Index public static readonly string COMPOUND_FILE_ENTRIES_EXTENSION = "cfe"; /// <summary> - /// this array contains all filename extensions used by + /// This array contains all filename extensions used by /// Lucene's index files, with one exception, namely the - /// extension made up from <code>.s</code> + a number. - /// Also note that Lucene's <code>segments_N</code> files + /// extension made up from <c>.s</c> + a number. + /// Also note that Lucene's <c>segments_N</c> files /// do not have any filename extension. /// </summary> public static readonly string[] INDEX_EXTENSIONS = new string[] { @@ -86,10 +86,11 @@ namespace Lucene.Net.Index /// <summary> /// Computes the full file name from base, extension and generation. If the - /// generation is -1, the file name is null. If it's 0, the file name is + /// generation is -1, the file name is <c>null</c>. If it's 0, the file name is /// <base>.<ext>. If it's > 0, the file name is - /// <base>_<gen>.<ext>.<br> - /// <b>NOTE:</b> .<ext> is added to the name only if <code>ext</code> is + /// <base>_<gen>.<ext>. + /// <para/> + /// <b>NOTE:</b> .<ext> is added to the name only if <c>ext</c> is /// not an empty string. /// </summary> /// <param name="base"> main part of the file name </param> @@ -125,13 +126,13 @@ namespace Lucene.Net.Index /// Returns a file name that includes the given segment name, your own custom /// name and extension. The format of the filename is: /// <segmentName>(_<name>)(.<ext>). - /// <p> + /// <para/> /// <b>NOTE:</b> .<ext> is added to the result file name only if /// <code>ext</code> is not empty. - /// <p> + /// <para/> /// <b>NOTE:</b> _<segmentSuffix> is added to the result file name only if /// it's not the empty string - /// <p> + /// <para/> /// <b>NOTE:</b> all custom files should be named using this method, or /// otherwise some structures may fail to handle them properly (such as if they /// are added to compound files). @@ -160,7 +161,7 @@ namespace Lucene.Net.Index } /// <summary> - /// Returns true if the given filename ends with the given extension. One + /// Returns <c>true</c> if the given filename ends with the given extension. One /// should provide a <i>pure</i> extension, without '.'. /// </summary> public static bool MatchesExtension(string filename, string ext) @@ -171,7 +172,7 @@ namespace Lucene.Net.Index } /// <summary> - /// locates the boundary of the segment name, or -1 </summary> + /// Locates the boundary of the segment name, or -1 </summary> private static int IndexOfSegmentName(string filename) { // If it is a .del file, there's an '_' after the first character @@ -186,7 +187,7 @@ namespace Lucene.Net.Index /// <summary> /// Strips the segment name out of the given file name. If you used - /// <seealso cref="#segmentFileName"/> or <seealso cref="#fileNameFromGeneration"/> to create your + /// <see cref="SegmentFileName"/> or <see cref="FileNameFromGeneration"/> to create your /// files, then this method simply removes whatever comes before the first '.', /// or the second '_' (excluding both). /// </summary> @@ -250,7 +251,7 @@ namespace Lucene.Net.Index /// <summary> /// All files created by codecs much match this pattern (checked in - /// SegmentInfo). + /// <see cref="SegmentInfo"/>). /// </summary> public static readonly Regex CODEC_FILE_PATTERN = new Regex("_[a-z0-9]+(_.*)?\\..*", RegexOptions.Compiled); } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/IndexFormatTooNewException.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/IndexFormatTooNewException.cs b/src/Lucene.Net/Index/IndexFormatTooNewException.cs index 772bef7..486abcd 100644 --- a/src/Lucene.Net/Index/IndexFormatTooNewException.cs +++ b/src/Lucene.Net/Index/IndexFormatTooNewException.cs @@ -26,7 +26,7 @@ namespace Lucene.Net.Index using DataInput = Lucene.Net.Store.DataInput; /// <summary> - /// this exception is thrown when Lucene detects + /// This exception is thrown when Lucene detects /// an index that is newer than this Lucene version. /// </summary> // LUCENENET: All exeption classes should be marked serializable @@ -36,14 +36,14 @@ namespace Lucene.Net.Index public class IndexFormatTooNewException : CorruptIndexException { /// <summary> - /// Creates an {@code IndexFormatTooNewException} + /// Creates an <see cref="IndexFormatTooNewException"/> + /// <para/> + /// @lucene.internal /// </summary> - /// <param name="resourceDesc"> describes the file that was too old </param> - /// <param name="version"> the version of the file that was too old </param> - /// <param name="minVersion"> the minimum version accepted </param> - /// <param name="maxVersion"> the maxium version accepted - /// - /// @lucene.internal </param> + /// <param name="resourceDesc"> describes the file that was too old </param> + /// <param name="version"> the version of the file that was too old </param> + /// <param name="minVersion"> the minimum version accepted </param> + /// <param name="maxVersion"> the maxium version accepted </param> public IndexFormatTooNewException(string resourceDesc, int version, int minVersion, int maxVersion) : base("Format version is not supported (resource: " + resourceDesc + "): " + version + " (needs to be between " + minVersion + " and " + maxVersion + ")") { @@ -51,14 +51,14 @@ namespace Lucene.Net.Index } /// <summary> - /// Creates an {@code IndexFormatTooNewException} + /// Creates an <see cref="IndexFormatTooNewException"/> + /// <para/> + /// @lucene.internal /// </summary> - /// <param name="input"> the open file that's too old </param> - /// <param name="version"> the version of the file that was too old </param> - /// <param name="minVersion"> the minimum version accepted </param> - /// <param name="maxVersion"> the maxium version accepted - /// - /// @lucene.internal </param> + /// <param name="input"> the open file that's too old </param> + /// <param name="version"> the version of the file that was too old </param> + /// <param name="minVersion"> the minimum version accepted </param> + /// <param name="maxVersion"> the maxium version accepted </param> public IndexFormatTooNewException(DataInput input, int version, int minVersion, int maxVersion) : this(input.ToString(), version, minVersion, maxVersion) { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/IndexFormatTooOldException.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/IndexFormatTooOldException.cs b/src/Lucene.Net/Index/IndexFormatTooOldException.cs index 013ed42..58af882 100644 --- a/src/Lucene.Net/Index/IndexFormatTooOldException.cs +++ b/src/Lucene.Net/Index/IndexFormatTooOldException.cs @@ -26,7 +26,7 @@ namespace Lucene.Net.Index using DataInput = Lucene.Net.Store.DataInput; /// <summary> - /// this exception is thrown when Lucene detects + /// This exception is thrown when Lucene detects /// an index that is too old for this Lucene version /// </summary> // LUCENENET: All exeption classes should be marked serializable @@ -36,12 +36,12 @@ namespace Lucene.Net.Index public class IndexFormatTooOldException : CorruptIndexException { /// <summary> - /// Creates an {@code IndexFormatTooOldException}. + /// Creates an <see cref="IndexFormatTooOldException"/>. + /// <para/> + /// @lucene.internal /// </summary> - /// <param name="resourceDesc"> describes the file that was too old </param> - /// <param name="version"> the version of the file that was too old - /// - /// @lucene.internal </param> + /// <param name="resourceDesc"> describes the file that was too old </param> + /// <param name="version"> the version of the file that was too old </param> public IndexFormatTooOldException(string resourceDesc, string version) : base("Format version is not supported (resource: " + resourceDesc + "): " + version + ". this version of Lucene only supports indexes created with release 3.0 and later.") { @@ -49,26 +49,26 @@ namespace Lucene.Net.Index } /// <summary> - /// Creates an {@code IndexFormatTooOldException}. + /// Creates an <see cref="IndexFormatTooOldException"/>. + /// <para/> + /// @lucene.internal /// </summary> - /// <param name="input"> the open file that's too old </param> - /// <param name="version"> the version of the file that was too old - /// - /// @lucene.internal </param> + /// <param name="input"> the open file that's too old </param> + /// <param name="version"> the version of the file that was too old </param> public IndexFormatTooOldException(DataInput input, string version) : this(input.ToString(), version) { } /// <summary> - /// Creates an {@code IndexFormatTooOldException}. + /// Creates an <see cref="IndexFormatTooOldException"/>. + /// <para/> + /// @lucene.internal /// </summary> - /// <param name="resourceDesc"> describes the file that was too old </param> - /// <param name="version"> the version of the file that was too old </param> - /// <param name="minVersion"> the minimum version accepted </param> - /// <param name="maxVersion"> the maxium version accepted - /// - /// @lucene.internal </param> + /// <param name="resourceDesc"> describes the file that was too old </param> + /// <param name="version"> the version of the file that was too old </param> + /// <param name="minVersion"> the minimum version accepted </param> + /// <param name="maxVersion"> the maxium version accepted </param> public IndexFormatTooOldException(string resourceDesc, int version, int minVersion, int maxVersion) : base("Format version is not supported (resource: " + resourceDesc + "): " + version + " (needs to be between " + minVersion + " and " + maxVersion + "). this version of Lucene only supports indexes created with release 3.0 and later.") { @@ -76,14 +76,14 @@ namespace Lucene.Net.Index } /// <summary> - /// Creates an {@code IndexFormatTooOldException}. + /// Creates an <see cref="IndexFormatTooOldException"/>. + /// <para/> + /// @lucene.internal /// </summary> - /// <param name="input"> the open file that's too old </param> - /// <param name="version"> the version of the file that was too old </param> - /// <param name="minVersion"> the minimum version accepted </param> - /// <param name="maxVersion"> the maxium version accepted - /// - /// @lucene.internal </param> + /// <param name="input"> the open file that's too old </param> + /// <param name="version"> the version of the file that was too old </param> + /// <param name="minVersion"> the minimum version accepted </param> + /// <param name="maxVersion"> the maxium version accepted </param> public IndexFormatTooOldException(DataInput input, int version, int minVersion, int maxVersion) : this(input.ToString(), version, minVersion, maxVersion) { http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/IndexNotFoundException.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/IndexNotFoundException.cs b/src/Lucene.Net/Index/IndexNotFoundException.cs index 6d15caa..221c6ca 100644 --- a/src/Lucene.Net/Index/IndexNotFoundException.cs +++ b/src/Lucene.Net/Index/IndexNotFoundException.cs @@ -24,7 +24,7 @@ namespace Lucene.Net.Index */ /// <summary> - /// Signals that no index was found in the Directory. Possibly because the + /// Signals that no index was found in the <see cref="Directory"/>. Possibly because the /// directory is empty, however can also indicate an index corruption. /// </summary> // LUCENENET: All exeption classes should be marked serializable @@ -34,8 +34,8 @@ namespace Lucene.Net.Index public sealed class IndexNotFoundException : FileNotFoundException { /// <summary> - /// Creates IndexFileNotFoundException with the - /// description message. + /// Creates <see cref="IndexNotFoundException"/> with the + /// description message. /// </summary> public IndexNotFoundException(string msg) : base(msg) http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/IndexReaderContext.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/IndexReaderContext.cs b/src/Lucene.Net/Index/IndexReaderContext.cs index d246a98..4df5432 100644 --- a/src/Lucene.Net/Index/IndexReaderContext.cs +++ b/src/Lucene.Net/Index/IndexReaderContext.cs @@ -22,7 +22,7 @@ namespace Lucene.Net.Index /// <summary> /// A struct like class that represents a hierarchical relationship between - /// <seealso cref="IndexReader"/> instances. + /// <see cref="IndexReader"/> instances. /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -34,15 +34,15 @@ namespace Lucene.Net.Index public CompositeReaderContext Parent { get; private set; } /// <summary> - /// <code>true</code> if this context struct represents the top level reader within the hierarchical context </summary> + /// <c>true</c> if this context struct represents the top level reader within the hierarchical context </summary> public bool IsTopLevel { get; private set; } /// <summary> - /// the doc base for this reader in the parent, <tt>0</tt> if parent is null </summary> + /// the doc base for this reader in the parent, <c>0</c> if parent is <c>null</c> </summary> public int DocBaseInParent { get; private set; } /// <summary> - /// the ord for this reader in the parent, <tt>0</tt> if parent is null </summary> + /// the ord for this reader in the parent, <c>0</c> if parent is <c>null</c> </summary> public int OrdInParent { get; private set; } internal IndexReaderContext(CompositeReaderContext parent, int ordInParent, int docBaseInParent) @@ -58,22 +58,22 @@ namespace Lucene.Net.Index } /// <summary> - /// Returns the <seealso cref="IndexReader"/>, this context represents. </summary> + /// Returns the <see cref="IndexReader"/>, this context represents. </summary> public abstract IndexReader Reader { get; } /// <summary> /// Returns the context's leaves if this context is a top-level context. - /// For convenience, if this is an <seealso cref="AtomicReaderContext"/> this + /// For convenience, if this is an <see cref="AtomicReaderContext"/> this /// returns itself as the only leaf. - /// <p>Note: this is convenience method since leaves can always be obtained by - /// walking the context tree using <seealso cref="#children()"/>. </summary> + /// <para/>Note: this is convenience method since leaves can always be obtained by + /// walking the context tree using <see cref="Children"/>. </summary> /// <exception cref="InvalidOperationException"> if this is not a top-level context. </exception> - /// <seealso cref= #children() </seealso> + /// <seealso cref="Children"/> public abstract IList<AtomicReaderContext> Leaves { get; } /// <summary> /// Returns the context's children iff this context is a composite context - /// otherwise <code>null</code>. + /// otherwise <c>null</c>. /// </summary> public abstract IList<IndexReaderContext> Children { get; } } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/IndexUpgrader.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/IndexUpgrader.cs b/src/Lucene.Net/Index/IndexUpgrader.cs index 1ad8e13..c99323a 100644 --- a/src/Lucene.Net/Index/IndexUpgrader.cs +++ b/src/Lucene.Net/Index/IndexUpgrader.cs @@ -29,24 +29,26 @@ namespace Lucene.Net.Index using InfoStream = Lucene.Net.Util.InfoStream; /// <summary> - /// this is an easy-to-use tool that upgrades all segments of an index from previous Lucene versions + /// This is an easy-to-use tool that upgrades all segments of an index from previous Lucene versions /// to the current segment file format. It can be used from command line: - /// <pre> + /// <code> /// java -cp lucene-core.jar Lucene.Net.Index.IndexUpgrader [-delete-prior-commits] [-verbose] indexDir - /// </pre> - /// Alternatively this class can be instantiated and <seealso cref="#upgrade"/> invoked. It uses <seealso cref="UpgradeIndexMergePolicy"/> - /// and triggers the upgrade via an forceMerge request to <seealso cref="IndexWriter"/>. - /// <p>this tool keeps only the last commit in an index; for this + /// </code> + /// Alternatively this class can be instantiated and <see cref="Upgrade()"/> invoked. It uses <see cref="UpgradeIndexMergePolicy"/> + /// and triggers the upgrade via an <see cref="IndexWriter.ForceMerge(int)"/> request to <see cref="IndexWriter"/>. + /// <para/> + /// This tool keeps only the last commit in an index; for this /// reason, if the incoming index has more than one commit, the tool - /// refuses to run by default. Specify {@code -delete-prior-commits} + /// refuses to run by default. Specify <c>-delete-prior-commits</c> /// to override this, allowing the tool to delete all but the last commit. - /// From Java code this can be enabled by passing {@code true} to - /// <seealso cref="#IndexUpgrader(Directory,Version,StreamWriter,boolean)"/>. - /// <p><b>Warning:</b> this tool may reorder documents if the index was partially + /// From .NET code this can be enabled by passing <c>true</c> to + /// <see cref="IndexUpgrader(Directory, LuceneVersion, TextWriter, bool)"/>. + /// <para/> + /// <b>Warning:</b> this tool may reorder documents if the index was partially /// upgraded before execution (e.g., documents were added). If your application relies /// on "monotonicity" of doc IDs (which means that the order in which the documents - /// were added to the index is preserved), do a full forceMerge instead. - /// The <seealso cref="MergePolicy"/> set by <seealso cref="IndexWriterConfig"/> may also reorder + /// were added to the index is preserved), do a full ForceMerge instead. + /// The <see cref="MergePolicy"/> set by <see cref="IndexWriterConfig"/> may also reorder /// documents. /// </summary> public sealed class IndexUpgrader @@ -66,13 +68,13 @@ namespace Lucene.Net.Index } /// <summary> - /// Main method to run {code IndexUpgrader} from the - /// command-line. + /// Main method to run <see cref="IndexUpgrader"/> from the + /// command-line. /// </summary> - /*public static void Main(string[] args) + public static void Main(string[] args) { - ParseArgs(args).Upgrade(); - }*/ + ParseArgs(args).Upgrade(); + } public static IndexUpgrader ParseArgs(string[] args) { @@ -136,8 +138,8 @@ namespace Lucene.Net.Index private readonly bool deletePriorCommits; /// <summary> - /// Creates index upgrader on the given directory, using an <seealso cref="IndexWriter"/> using the given - /// {@code matchVersion}. The tool refuses to upgrade indexes with multiple commit points. + /// Creates index upgrader on the given directory, using an <see cref="IndexWriter"/> using the given + /// <paramref name="matchVersion"/>. The tool refuses to upgrade indexes with multiple commit points. /// </summary> public IndexUpgrader(Directory dir, LuceneVersion matchVersion) : this(dir, new IndexWriterConfig(matchVersion, null), false) @@ -145,9 +147,9 @@ namespace Lucene.Net.Index } /// <summary> - /// Creates index upgrader on the given directory, using an <seealso cref="IndexWriter"/> using the given - /// {@code matchVersion}. You have the possibility to upgrade indexes with multiple commit points by removing - /// all older ones. If {@code infoStream} is not {@code null}, all logging output will be sent to this stream. + /// Creates index upgrader on the given directory, using an <see cref="IndexWriter"/> using the given + /// <paramref name="matchVersion"/>. You have the possibility to upgrade indexes with multiple commit points by removing + /// all older ones. If <paramref name="infoStream"/> is not <c>null</c>, all logging output will be sent to this stream. /// </summary> public IndexUpgrader(Directory dir, LuceneVersion matchVersion, TextWriter infoStream, bool deletePriorCommits) : this(dir, new IndexWriterConfig(matchVersion, null), deletePriorCommits) @@ -159,7 +161,7 @@ namespace Lucene.Net.Index } /// <summary> - /// Creates index upgrader on the given directory, using an <seealso cref="IndexWriter"/> using the given + /// Creates index upgrader on the given directory, using an <see cref="IndexWriter"/> using the given /// config. You have the possibility to upgrade indexes with multiple commit points by removing /// all older ones. /// </summary> http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/IndexWriterConfig.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/IndexWriterConfig.cs b/src/Lucene.Net/Index/IndexWriterConfig.cs index 3ce6890..ffc21c2 100644 --- a/src/Lucene.Net/Index/IndexWriterConfig.cs +++ b/src/Lucene.Net/Index/IndexWriterConfig.cs @@ -393,7 +393,7 @@ namespace Lucene.Net.Index /// Expert: <see cref="Index.MergePolicy"/> is invoked whenever there are changes to the /// segments in the index. Its role is to select which merges to do, if any, /// and return a <see cref="MergePolicy.MergeSpecification"/> describing the merges. - /// It also selects merges to do for forceMerge. + /// It also selects merges to do for <see cref="IndexWriter.ForceMerge(int)"/>. /// /// <para/>Only takes effect when <see cref="IndexWriter"/> is first created. /// </summary> http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/IndexableField.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/IndexableField.cs b/src/Lucene.Net/Index/IndexableField.cs index c473def..99d09f7 100644 --- a/src/Lucene.Net/Index/IndexableField.cs +++ b/src/Lucene.Net/Index/IndexableField.cs @@ -28,12 +28,11 @@ namespace Lucene.Net.Index // TODO: we need to break out separate StoredField... /// <summary> - /// Represents a single field for indexing. IndexWriter - /// consumes Iterable<IndexableField> as a document. - /// - /// @lucene.experimental + /// Represents a single field for indexing. <see cref="IndexWriter"/> + /// consumes IEnumerable<IndexableField> as a document. + /// <para/> + /// @lucene.experimental /// </summary> - public interface IIndexableField { /// <summary> @@ -41,30 +40,31 @@ namespace Lucene.Net.Index string Name { get; } /// <summary> - /// <seealso cref="IIndexableFieldType"/> describing the properties + /// <see cref="IIndexableFieldType"/> describing the properties /// of this field. /// </summary> IIndexableFieldType FieldType { get; } /// <summary> /// Returns the field's index-time boost. - /// <p> + /// <para/> /// Only fields can have an index-time boost, if you want to simulate /// a "document boost", then you must pre-multiply it across all the /// relevant fields yourself. - /// <p>The boost is used to compute the norm factor for the field. By - /// default, in the <seealso cref="Similarity#computeNorm(FieldInvertState)"/> method, + /// <para/> + /// The boost is used to compute the norm factor for the field. By + /// default, in the <see cref="Search.Similarities.Similarity.ComputeNorm(FieldInvertState)"/> method, /// the boost value is multiplied by the length normalization factor and then - /// rounded by <seealso cref="DefaultSimilarity#encodeNormValue(float)"/> before it is stored in the + /// rounded by <see cref="Search.Similarities.DefaultSimilarity.EncodeNormValue(float)"/> before it is stored in the /// index. One should attempt to ensure that this product does not overflow /// the range of that encoding. - /// <p> + /// <para/> /// It is illegal to return a boost other than 1.0f for a field that is not - /// indexed (<seealso cref="IIndexableFieldType#indexed()"/> is false) or omits normalization values - /// (<seealso cref="IIndexableFieldType#omitNorms()"/> returns true). + /// indexed (<see cref="IIndexableFieldType.IsIndexed"/> is false) or omits normalization values + /// (<see cref="IIndexableFieldType.OmitNorms"/> returns true). /// </summary> - /// <seealso cref= Similarity#computeNorm(FieldInvertState) </seealso> - /// <seealso cref= DefaultSimilarity#encodeNormValue(float) </seealso> + /// <seealso cref="Search.Similarities.Similarity.ComputeNorm(FieldInvertState)"/> + /// <seealso cref="Search.Similarities.DefaultSimilarity.EncodeNormValue(float)"/> float Boost { get; } /// <summary> @@ -76,7 +76,7 @@ namespace Lucene.Net.Index string GetStringValue(); /// <summary> - /// Non-null if this field has a TextReader value </summary> + /// Non-null if this field has a <see cref="TextReader"/> value </summary> TextReader GetReaderValue(); /// <summary> @@ -84,13 +84,13 @@ namespace Lucene.Net.Index object GetNumericValue(); // LUCENENET TODO: Can we eliminate object? /// <summary> - /// Creates the TokenStream used for indexing this field. If appropriate, - /// implementations should use the given Analyzer to create the TokenStreams. + /// Creates the <see cref="TokenStream"/> used for indexing this field. If appropriate, + /// implementations should use the given <see cref="Analyzer"/> to create the <see cref="TokenStream"/>s. /// </summary> - /// <param name="analyzer"> Analyzer that should be used to create the TokenStreams from </param> - /// <returns> TokenStream value for indexing the document. Should always return + /// <param name="analyzer"> <see cref="Analyzer"/> that should be used to create the <see cref="TokenStream"/>s from </param> + /// <returns> <see cref="TokenStream"/> value for indexing the document. Should always return /// a non-null value if the field is to be indexed </returns> - /// <exception cref="IOException"> Can be thrown while creating the TokenStream </exception> + /// <exception cref="IOException"> Can be thrown while creating the <see cref="TokenStream"/> </exception> TokenStream GetTokenStream(Analyzer analyzer); } } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/IndexableFieldType.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/IndexableFieldType.cs b/src/Lucene.Net/Index/IndexableFieldType.cs index e61cbde..bdb2b1a 100644 --- a/src/Lucene.Net/Index/IndexableFieldType.cs +++ b/src/Lucene.Net/Index/IndexableFieldType.cs @@ -21,69 +21,70 @@ namespace Lucene.Net.Index /// <summary> /// Describes the properties of a field. + /// <para/> /// @lucene.experimental /// </summary> public interface IIndexableFieldType { /// <summary> - /// True if this field should be indexed (inverted) </summary> + /// <c>true</c> if this field should be indexed (inverted) </summary> bool IsIndexed { get; } /// <summary> - /// True if the field's value should be stored </summary> + /// <c>true</c> if the field's value should be stored </summary> bool IsStored { get; } /// <summary> - /// True if this field's value should be analyzed by the - /// <seealso cref="Analyzer"/>. - /// <p> - /// this has no effect if <seealso cref="#indexed()"/> returns false. + /// <c>true</c> if this field's value should be analyzed by the + /// <see cref="Analysis.Analyzer"/>. + /// <para/> + /// This has no effect if <see cref="IsIndexed"/> returns <c>false</c>. /// </summary> bool IsTokenized { get; } /// <summary> - /// True if this field's indexed form should be also stored + /// <c>true</c> if this field's indexed form should be also stored /// into term vectors. - /// <p> + /// <para/> /// this builds a miniature inverted-index for this field which /// can be accessed in a document-oriented way from - /// <seealso cref="IndexReader#getTermVector(int,String)"/>. - /// <p> - /// this option is illegal if <seealso cref="#indexed()"/> returns false. + /// <see cref="IndexReader.GetTermVector(int, string)"/>. + /// <para/> + /// This option is illegal if <see cref="IsIndexed"/> returns <c>false</c>. /// </summary> bool StoreTermVectors { get; } /// <summary> - /// True if this field's token character offsets should also + /// <c>true</c> if this field's token character offsets should also /// be stored into term vectors. - /// <p> - /// this option is illegal if term vectors are not enabled for the field - /// (<seealso cref="#storeTermVectors()"/> is false) + /// <para/> + /// This option is illegal if term vectors are not enabled for the field + /// (<see cref="StoreTermVectors"/> is <c>false</c>) /// </summary> bool StoreTermVectorOffsets { get; } /// <summary> - /// True if this field's token positions should also be stored + /// <c>true</c> if this field's token positions should also be stored /// into the term vectors. - /// <p> - /// this option is illegal if term vectors are not enabled for the field - /// (<seealso cref="#storeTermVectors()"/> is false). + /// <para/> + /// This option is illegal if term vectors are not enabled for the field + /// (<see cref="StoreTermVectors"/> is <c>false</c>). /// </summary> bool StoreTermVectorPositions { get; } /// <summary> - /// True if this field's token payloads should also be stored + /// <c>true</c> if this field's token payloads should also be stored /// into the term vectors. - /// <p> - /// this option is illegal if term vector positions are not enabled - /// for the field (<seealso cref="#storeTermVectors()"/> is false). + /// <para/> + /// This option is illegal if term vector positions are not enabled + /// for the field (<see cref="StoreTermVectors"/> is <c>false</c>). /// </summary> bool StoreTermVectorPayloads { get; } /// <summary> - /// True if normalization values should be omitted for the field. + /// <c>true</c> if normalization values should be omitted for the field. /// <para/> - /// this saves memory, but at the expense of scoring quality (length normalization + /// This saves memory, but at the expense of scoring quality (length normalization /// will be disabled), and if you omit norms, you cannot use index-time boosts. /// </summary> bool OmitNorms { get; } http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/KeepOnlyLastCommitDeletionPolicy.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/KeepOnlyLastCommitDeletionPolicy.cs b/src/Lucene.Net/Index/KeepOnlyLastCommitDeletionPolicy.cs index 05b6ce2..1451327 100644 --- a/src/Lucene.Net/Index/KeepOnlyLastCommitDeletionPolicy.cs +++ b/src/Lucene.Net/Index/KeepOnlyLastCommitDeletionPolicy.cs @@ -21,9 +21,9 @@ namespace Lucene.Net.Index */ /// <summary> - /// this <seealso cref="IndexDeletionPolicy"/> implementation that + /// This <see cref="IndexDeletionPolicy"/> implementation that /// keeps only the most recent commit and immediately removes - /// all prior commits after a new commit is done. this is + /// all prior commits after a new commit is done. This is /// the default deletion policy. /// </summary> #if FEATURE_SERIALIZABLE http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/LogByteSizeMergePolicy.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/LogByteSizeMergePolicy.cs b/src/Lucene.Net/Index/LogByteSizeMergePolicy.cs index 624a78a..2311597 100644 --- a/src/Lucene.Net/Index/LogByteSizeMergePolicy.cs +++ b/src/Lucene.Net/Index/LogByteSizeMergePolicy.cs @@ -20,30 +20,33 @@ namespace Lucene.Net.Index */ /// <summary> - /// this is a <seealso cref="LogMergePolicy"/> that measures size of a - /// segment as the total byte size of the segment's files. + /// This is a <see cref="LogMergePolicy"/> that measures size of a + /// segment as the total byte size of the segment's files. /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif public class LogByteSizeMergePolicy : LogMergePolicy { - /// Default minimum segment size. <seealso cref= setMinMergeMB </seealso> + /// <summary>Default minimum segment size. </summary> + /// <seealso cref="MinMergeMB"/> public static readonly double DEFAULT_MIN_MERGE_MB = 1.6; /// <summary> - /// Default maximum segment size. A segment of this size </summary> - /// or larger will never be merged. <seealso cref= setMaxMergeMB </seealso> + /// Default maximum segment size. A segment of this size + /// or larger will never be merged. </summary> + /// <seealso cref="MaxMergeMB"/> public static readonly double DEFAULT_MAX_MERGE_MB = 2048; /// <summary> - /// Default maximum segment size. A segment of this size </summary> - /// or larger will never be merged during forceMerge. <seealso cref= setMaxMergeMBForForceMerge </seealso> + /// Default maximum segment size. A segment of this size + /// or larger will never be merged during <see cref="IndexWriter.ForceMerge(int)"/>. </summary> + /// <seealso cref="MaxMergeMBForForcedMerge"/> public static readonly double DEFAULT_MAX_MERGE_MB_FOR_FORCED_MERGE = long.MaxValue; /// <summary> /// Sole constructor, setting all settings to their - /// defaults. + /// defaults. /// </summary> public LogByteSizeMergePolicy() { @@ -64,17 +67,17 @@ namespace Lucene.Net.Index } /// <summary> - /// <p>Determines the largest segment (measured by total - /// byte size of the segment's files, in MB) that may be - /// merged with other segments. Small values (e.g., less - /// than 50 MB) are best for interactive indexing, as this - /// limits the length of pauses while indexing to a few - /// seconds. Larger values are best for batched indexing - /// and speedier searches.</p> + /// <para>Determines the largest segment (measured by total + /// byte size of the segment's files, in MB) that may be + /// merged with other segments. Small values (e.g., less + /// than 50 MB) are best for interactive indexing, as this + /// limits the length of pauses while indexing to a few + /// seconds. Larger values are best for batched indexing + /// and speedier searches.</para> /// - /// <p>Note that <seealso cref="#setMaxMergeDocs"/> is also - /// used to check whether a segment is too large for - /// merging (it's either or).</p> + /// <para>Note that <see cref="LogMergePolicy.MaxMergeDocs"/> is also + /// used to check whether a segment is too large for + /// merging (it's either or).</para> /// </summary> public virtual double MaxMergeMB { @@ -93,11 +96,11 @@ namespace Lucene.Net.Index } /// <summary> - /// <p>Determines the largest segment (measured by total - /// byte size of the segment's files, in MB) that may be - /// merged with other segments during forceMerge. Setting - /// it low will leave the index with more than 1 segment, - /// even if <seealso cref="IndexWriter#forceMerge"/> is called. + /// Determines the largest segment (measured by total + /// byte size of the segment's files, in MB) that may be + /// merged with other segments during forceMerge. Setting + /// it low will leave the index with more than 1 segment, + /// even if <see cref="IndexWriter.ForceMerge(int)"/> is called. /// </summary> public virtual double MaxMergeMBForForcedMerge { @@ -120,7 +123,7 @@ namespace Lucene.Net.Index /// Any segments below this size are considered to be on /// the same level (even if they vary drastically in size) /// and will be merged whenever there are mergeFactor of - /// them. this effectively truncates the "long tail" of + /// them. This effectively truncates the "long tail" of /// small segments that would otherwise be created into a /// single level. If you set this too large, it could /// greatly increase the merging cost during indexing (if http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/LogDocMergePolicy.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/LogDocMergePolicy.cs b/src/Lucene.Net/Index/LogDocMergePolicy.cs index 397e1f4..d514efe 100644 --- a/src/Lucene.Net/Index/LogDocMergePolicy.cs +++ b/src/Lucene.Net/Index/LogDocMergePolicy.cs @@ -20,21 +20,22 @@ namespace Lucene.Net.Index */ /// <summary> - /// this is a <seealso cref="LogMergePolicy"/> that measures size of a - /// segment as the number of documents (not taking deletions - /// into account). + /// This is a <see cref="LogMergePolicy"/> that measures size of a + /// segment as the number of documents (not taking deletions + /// into account). /// </summary> #if FEATURE_SERIALIZABLE [Serializable] #endif public class LogDocMergePolicy : LogMergePolicy { - /// Default minimum segment size. <seealso cref= setMinMergeDocs </seealso> + /// <summary> Default minimum segment size. </summary> + /// <seealso cref="MinMergeDocs"/> public static readonly int DEFAULT_MIN_MERGE_DOCS = 1000; /// <summary> /// Sole constructor, setting all settings to their - /// defaults. + /// defaults. /// </summary> public LogDocMergePolicy() { @@ -56,7 +57,7 @@ namespace Lucene.Net.Index /// Any segments below this size are considered to be on /// the same level (even if they vary drastically in size) /// and will be merged whenever there are mergeFactor of - /// them. this effectively truncates the "long tail" of + /// them. This effectively truncates the "long tail" of /// small segments that would otherwise be created into a /// single level. If you set this too large, it could /// greatly increase the merging cost during indexing (if http://git-wip-us.apache.org/repos/asf/lucenenet/blob/530d26bb/src/Lucene.Net/Index/LogMergePolicy.cs ---------------------------------------------------------------------- diff --git a/src/Lucene.Net/Index/LogMergePolicy.cs b/src/Lucene.Net/Index/LogMergePolicy.cs index 4c2b3ab..35324d1 100644 --- a/src/Lucene.Net/Index/LogMergePolicy.cs +++ b/src/Lucene.Net/Index/LogMergePolicy.cs @@ -25,22 +25,21 @@ namespace Lucene.Net.Index */ /// <summary> - /// <p>this class implements a <seealso cref="MergePolicy"/> that tries + /// <para>This class implements a <see cref="MergePolicy"/> that tries /// to merge segments into levels of exponentially /// increasing size, where each level has fewer segments than /// the value of the merge factor. Whenever extra segments /// (beyond the merge factor upper bound) are encountered, /// all segments within the level are merged. You can get or - /// set the merge factor using <seealso cref="#getMergeFactor()"/> and - /// <seealso cref="#setMergeFactor(int)"/> respectively.</p> + /// set the merge factor using <see cref="MergeFactor"/>.</para> /// - /// <p>this class is abstract and requires a subclass to - /// define the <seealso cref="#size"/> method which specifies how a - /// segment's size is determined. <seealso cref="LogDocMergePolicy"/> + /// <para>This class is abstract and requires a subclass to + /// define the <see cref="MergePolicy.Size(SegmentCommitInfo)"/> method which specifies how a + /// segment's size is determined. <see cref="LogDocMergePolicy"/> /// is one subclass that measures size by document count in - /// the segment. <seealso cref="LogByteSizeMergePolicy"/> is another + /// the segment. <see cref="LogByteSizeMergePolicy"/> is another /// subclass that measures size as the total byte size of the - /// file(s) for the segment.</p> + /// file(s) for the segment.</para> /// </summary> #if FEATURE_SERIALIZABLE [Serializable] @@ -49,27 +48,28 @@ namespace Lucene.Net.Index { /// <summary> /// Defines the allowed range of log(size) for each - /// level. A level is computed by taking the max segment - /// log size, minus LEVEL_LOG_SPAN, and finding all - /// segments falling within that range. + /// level. A level is computed by taking the max segment + /// log size, minus LEVEL_LOG_SPAN, and finding all + /// segments falling within that range. /// </summary> public static readonly double LEVEL_LOG_SPAN = 0.75; /// <summary> /// Default merge factor, which is how many segments are - /// merged at a time + /// merged at a time /// </summary> public static readonly int DEFAULT_MERGE_FACTOR = 10; /// <summary> - /// Default maximum segment size. A segment of this size </summary> - /// or larger will never be merged. <seealso cref= setMaxMergeDocs </seealso> + /// Default maximum segment size. A segment of this size + /// or larger will never be merged. </summary> + /// <seealso cref="MaxMergeDocs"/> public static readonly int DEFAULT_MAX_MERGE_DOCS = int.MaxValue; /// <summary> /// Default noCFSRatio. If a merge's size is >= 10% of - /// the index, then we disable compound file for it. </summary> - /// <seealso cref= MergePolicy#setNoCFSRatio </seealso> + /// the index, then we disable compound file for it. </summary> + /// <seealso cref="MergePolicy.NoCFSRatio"/> public new static readonly double DEFAULT_NO_CFS_RATIO = 0.1; /// <summary> @@ -78,14 +78,14 @@ namespace Lucene.Net.Index /// <summary> /// Any segments whose size is smaller than this value - /// will be rounded up to this value. this ensures that - /// tiny segments are aggressively merged. + /// will be rounded up to this value. This ensures that + /// tiny segments are aggressively merged. /// </summary> protected long m_minMergeSize; /// <summary> /// If the size of a segment exceeds this value then it - /// will never be merged. + /// will never be merged. /// </summary> protected long m_maxMergeSize; @@ -93,25 +93,25 @@ namespace Lucene.Net.Index // out there wrote his own LMP ... /// <summary> /// If the size of a segment exceeds this value then it - /// will never be merged during <seealso cref="IndexWriter#forceMerge"/>. + /// will never be merged during <see cref="IndexWriter.ForceMerge(int)"/>. /// </summary> protected long m_maxMergeSizeForForcedMerge = long.MaxValue; /// <summary> /// If a segment has more than this many documents then it - /// will never be merged. + /// will never be merged. /// </summary> protected int m_maxMergeDocs = DEFAULT_MAX_MERGE_DOCS; /// <summary> /// If true, we pro-rate a segment's size by the - /// percentage of non-deleted documents. + /// percentage of non-deleted documents. /// </summary> protected bool m_calibrateSizeByDeletes = true; /// <summary> /// Sole constructor. (For invocation by subclass - /// constructors, typically implicit.) + /// constructors, typically implicit.) /// </summary> public LogMergePolicy() : base(DEFAULT_NO_CFS_RATIO, MergePolicy.DEFAULT_MAX_CFS_SEGMENT_SIZE) @@ -131,8 +131,7 @@ namespace Lucene.Net.Index } /// <summary> - /// Print a debug message to <seealso cref="IndexWriter"/>'s {@code - /// infoStream}. + /// Print a debug message to <see cref="IndexWriter.infoStream"/>. /// </summary> protected virtual void Message(string message) { @@ -148,7 +147,7 @@ namespace Lucene.Net.Index /// allowed to accumulate in the index. /// <para/> /// This determines how often segment indices are merged by - /// AddDocument(). With smaller values, less RAM is used + /// <see cref="IndexWriter.AddDocument(IEnumerable{IIndexableField})"/>. With smaller values, less RAM is used /// while indexing, and searches are /// faster, but indexing speed is slower. With larger /// values, more RAM is used during indexing, and while @@ -175,7 +174,7 @@ namespace Lucene.Net.Index /// <summary> /// Gets or Sets whether the segment size should be calibrated by - /// the number of deletes when choosing segments for merge. + /// the number of deletes when choosing segments for merge. /// </summary> public virtual bool CalibrateSizeByDeletes { @@ -194,10 +193,10 @@ namespace Lucene.Net.Index } /// <summary> - /// Return the number of documents in the provided {@link - /// SegmentCommitInfo}, pro-rated by percentage of - /// non-deleted documents if {@link - /// #setCalibrateSizeByDeletes} is set. + /// Return the number of documents in the provided + /// <see cref="SegmentCommitInfo"/>, pro-rated by percentage of + /// non-deleted documents if + /// <see cref="CalibrateSizeByDeletes"/> is set. /// </summary> protected virtual long SizeDocs(SegmentCommitInfo info) { @@ -214,10 +213,10 @@ namespace Lucene.Net.Index } /// <summary> - /// Return the byte size of the provided {@link - /// SegmentCommitInfo}, pro-rated by percentage of - /// non-deleted documents if {@link - /// #setCalibrateSizeByDeletes} is set. + /// Return the byte size of the provided + /// <see cref="SegmentCommitInfo"/>, pro-rated by percentage of + /// non-deleted documents if + /// <see cref="CalibrateSizeByDeletes"/> is set. /// </summary> protected virtual long SizeBytes(SegmentCommitInfo info) { @@ -229,9 +228,9 @@ namespace Lucene.Net.Index } /// <summary> - /// Returns true if the number of segments eligible for - /// merging is less than or equal to the specified {@code - /// maxNumSegments}. + /// Returns <c>true</c> if the number of segments eligible for + /// merging is less than or equal to the specified + /// <paramref name="maxNumSegments"/>. /// </summary> protected virtual bool IsMerged(SegmentInfos infos, int maxNumSegments, IDictionary<SegmentCommitInfo, bool?> segmentsToMerge) { @@ -308,8 +307,8 @@ namespace Lucene.Net.Index } /// <summary> - /// Returns the merges necessary to forceMerge the index. this method constraints - /// the returned merges only by the {@code maxNumSegments} parameter, and + /// Returns the merges necessary to <see cref="IndexWriter.ForceMerge(int)"/> the index. this method constraints + /// the returned merges only by the <paramref name="maxNumSegments"/> parameter, and /// guaranteed that exactly that number of segments will remain in the index. /// </summary> private MergeSpecification FindForcedMergesMaxNumSegments(SegmentInfos infos, int maxNumSegments, int last) @@ -375,17 +374,18 @@ namespace Lucene.Net.Index return spec.Merges.Count == 0 ? null : spec; } + // LUCENENET TODO: Get rid of the nullable in IDictionary<SegmentCommitInfo, bool?>, if possible /// <summary> /// Returns the merges necessary to merge the index down - /// to a specified number of segments. - /// this respects the <seealso cref="#maxMergeSizeForForcedMerge"/> setting. - /// By default, and assuming {@code maxNumSegments=1}, only - /// one segment will be left in the index, where that segment - /// has no deletions pending nor separate norms, and it is in - /// compound file format if the current useCompoundFile - /// setting is true. this method returns multiple merges - /// (mergeFactor at a time) so the <seealso cref="MergeScheduler"/> - /// in use may make use of concurrency. + /// to a specified number of segments. + /// this respects the <see cref="m_maxMergeSizeForForcedMerge"/> setting. + /// By default, and assuming <c>maxNumSegments=1</c>, only + /// one segment will be left in the index, where that segment + /// has no deletions pending nor separate norms, and it is in + /// compound file format if the current useCompoundFile + /// setting is <c>true</c>. This method returns multiple merges + /// (mergeFactor at a time) so the <see cref="MergeScheduler"/> + /// in use may make use of concurrency. /// </summary> public override MergeSpecification FindForcedMerges(SegmentInfos infos, int maxNumSegments, IDictionary<SegmentCommitInfo, bool?> segmentsToMerge) { @@ -554,12 +554,12 @@ namespace Lucene.Net.Index /// <summary> /// Checks if any merges are now necessary and returns a - /// <seealso cref="MergePolicy.MergeSpecification"/> if so. A merge - /// is necessary when there are more than {@link - /// #setMergeFactor} segments at a given level. When - /// multiple levels have too many segments, this method - /// will return multiple merges, allowing the {@link - /// MergeScheduler} to use concurrency. + /// <see cref="MergePolicy.MergeSpecification"/> if so. A merge + /// is necessary when there are more than + /// <see cref="MergeFactor"/> segments at a given level. When + /// multiple levels have too many segments, this method + /// will return multiple merges, allowing the + /// <see cref="MergeScheduler"/> to use concurrency. /// </summary> public override MergeSpecification FindMerges(MergeTrigger mergeTrigger, SegmentInfos infos) { @@ -726,20 +726,20 @@ namespace Lucene.Net.Index } /// <summary> - /// <p>Determines the largest segment (measured by + /// <para>Determines the largest segment (measured by /// document count) that may be merged with other segments. /// Small values (e.g., less than 10,000) are best for /// interactive indexing, as this limits the length of /// pauses while indexing to a few seconds. Larger values /// are best for batched indexing and speedier - /// searches.</p> + /// searches.</para> /// - /// <p>The default value is <see cref="int.MaxValue"/>.</p> + /// <para>The default value is <see cref="int.MaxValue"/>.</para> /// - /// <p>The default merge policy ({@link - /// LogByteSizeMergePolicy}) also allows you to set this - /// limit by net size (in MB) of the segment, using {@link - /// LogByteSizeMergePolicy#setMaxMergeMB}.</p> + /// <para>The default merge policy + /// (<see cref="LogByteSizeMergePolicy"/>) also allows you to set this + /// limit by net size (in MB) of the segment, using + /// <see cref="LogByteSizeMergePolicy.MaxMergeMB"/>.</para> /// </summary> public virtual int MaxMergeDocs {
