[lucy-commits] git commit: refs/heads/master - Improve Indexer::Optimize() documentation

[nw...@apache.org]

Updated Branches:
  refs/heads/master 2c37b95ae -> b1d930cd7


Improve Indexer::Optimize() documentation

Add some of the comments Marvin made on lucy-user.


Project: http://git-wip-us.apache.org/repos/asf/lucy/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucy/commit/b1d930cd
Tree: http://git-wip-us.apache.org/repos/asf/lucy/tree/b1d930cd
Diff: http://git-wip-us.apache.org/repos/asf/lucy/diff/b1d930cd

Branch: refs/heads/master
Commit: b1d930cd72873629a15f12f12d01c965fbdb0099
Parents: 2c37b95
Author: Nick Wellnhofer <we...@aevum.de>
Authored: Tue Nov 27 13:26:27 2012 +0100
Committer: Nick Wellnhofer <we...@aevum.de>
Committed: Tue Nov 27 13:28:30 2012 +0100

----------------------------------------------------------------------
 core/Lucy/Index/Indexer.cfh |   16 ++++++++++++++++
 1 files changed, 16 insertions(+), 0 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/lucy/blob/b1d930cd/core/Lucy/Index/Indexer.cfh
----------------------------------------------------------------------
diff --git a/core/Lucy/Index/Indexer.cfh b/core/Lucy/Index/Indexer.cfh
index e316975..4dfc3dc 100644
--- a/core/Lucy/Index/Indexer.cfh
+++ b/core/Lucy/Index/Indexer.cfh
@@ -114,6 +114,22 @@ public class Lucy::Index::Indexer inherits Clownfish::Obj {
 
     /** Optimize the index for search-time performance.  This may take a
      * while, as it can involve rewriting large amounts of data.
+     *
+     * Every Indexer session which changes index content and ends in a
+     * Commit() creates a new segment.  Once written, segments are never
+     * modified.  However, they are periodically recycled by feeding their
+     * content into the segment currently being written.
+     *
+     * The Optimize() method causes all existing index content to be fed back
+     * into the Indexer.  When Commit() completes after an Optimize(), the
+     * index will consist of one segment.  So Optimize() must be called
+     * before Commit().  Also, optimizing a fresh index created from scratch
+     * has no effect.
+     *
+     * Historically, there was a significant search-time performance benefit
+     * to collapsing down to a single segment versus even two segments.  Now
+     * the effect of collapsing is much less significant, and calling
+     * Optimize() is rarely justified.
      */
     public void
     Optimize(Indexer *self);