From 061f31e910f0f6cb2ad4e7ed6d1b11325c38bc72 Mon Sep 17 00:00:00 2001
From: David Wayne Smiley <dsmiley@apache.org>
Date: Tue, 2 Apr 2013 15:07:45 +0000
Subject: [PATCH] LUCENE-4881: javadocs for SentinelIntSet

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1463587 13f79535-47bb-0310-9956-ffa450edef68
---
 .../apache/lucene/util/SentinelIntSet.java    | 39 +++++++++++++++----
 1 file changed, 31 insertions(+), 8 deletions(-)

diff --git a/lucene/core/src/java/org/apache/lucene/util/SentinelIntSet.java b/lucene/core/src/java/org/apache/lucene/util/SentinelIntSet.java
index ff209c64c54..935658372bf 100644
--- a/lucene/core/src/java/org/apache/lucene/util/SentinelIntSet.java
+++ b/lucene/core/src/java/org/apache/lucene/util/SentinelIntSet.java
@@ -20,26 +20,42 @@ package org.apache.lucene.util;
 import java.util.Arrays;
 
 /**
- * A native int set where one value is reserved to mean "EMPTY"
+ * A native int hash-based set where one value is reserved to mean "EMPTY" internally. The space overhead is fairly low
+ * as there is only one power-of-two sized int[] to hold the values.  The set is re-hashed when adding a value that
+ * would make it >= 75% full.  Consider extending and over-riding {@link #hash(int)} if the values might be poor
+ * hash keys; Lucene docids should be fine.
+ * The internal fields are exposed publicly to enable more efficient use at the expense of better O-O principles.
+ * <p/>
+ * To iterate over the integers held in this set, simply use code like this:
+ * <pre class="prettyprint">
+ * SentinelIntSet set = ...
+ * for (int v : set.keys) {
+ *   if (v == set.emptyVal)
+ *     continue;
+ *   //use v...
+ * }</pre>
  *
  * @lucene.internal
  */
 public class SentinelIntSet {
+  /** A power-of-2 over-sized array holding the integers in the set along with empty values. */
   public int[] keys;
   public int count;
   public final int emptyVal;
-  public int rehashCount;   // the count at which a rehash should be done
+  /** the count at which a rehash should be done */
+  public int rehashCount;
 
   /**
    *
-   * @param size  The minimum number of elements this set should be able to hold without re-hashing (i.e. the slots are guaranteed not to change)
+   * @param size  The minimum number of elements this set should be able to hold without rehashing
+   *              (i.e. the slots are guaranteed not to change)
    * @param emptyVal The integer value to use for EMPTY
    */
   public SentinelIntSet(int size, int emptyVal) {
     this.emptyVal = emptyVal;
     int tsize = Math.max(org.apache.lucene.util.BitUtil.nextHighestPowerOfTwo(size), 1);
     rehashCount = tsize - (tsize>>2);
-    if (size >= rehashCount) {  // should be able to hold "size" w/o rehashing
+    if (size >= rehashCount) {  // should be able to hold "size" w/o re-hashing
       tsize <<= 1;
       rehashCount = tsize - (tsize>>2);
     }
@@ -53,13 +69,17 @@ public class SentinelIntSet {
     count = 0;
   }
 
+  /** (internal) Return the hash for the key. The default implementation just returns the key,
+   * which is not appropriate for general purpose use.
+   */
   public int hash(int key) {
     return key;
   }
 
+  /** The number of integers in this set. */
   public int size() { return count; }
 
-  /** returns the slot for this key */
+  /** (internal) Returns the slot for this key */
   public int getSlot(int key) {
     assert key != emptyVal;
     int h = hash(key);
@@ -73,7 +93,7 @@ public class SentinelIntSet {
     return s;
   }
 
-  /** returns the slot for this key, or -slot-1 if not found */
+  /** (internal) Returns the slot for this key, or -slot-1 if not found */
   public int find(int key) {
     assert key != emptyVal;
     int h = hash(key);
@@ -89,10 +109,13 @@ public class SentinelIntSet {
     }
   }
 
+  /** Does this set contain the specified integer? */
   public boolean exists(int key) {
     return find(key) >= 0;
   }
 
+  /** Puts this integer (key) in the set, and returns the slot index it was added to.
+   * It rehashes if adding it would make the set more than 75% full. */
   public int put(int key) {
     int s = find(key);
     if (s < 0) {
@@ -108,14 +131,14 @@ public class SentinelIntSet {
     return s;
   }
 
+  /** (internal) Rehashes by doubling {@code int[] key} and filling with the old values. */
   public void rehash() {
     int newSize = keys.length << 1;
     int[] oldKeys = keys;
     keys = new int[newSize];
     if (emptyVal != 0) Arrays.fill(keys, emptyVal);
 
-    for (int i=0; i<oldKeys.length; i++) {
-      int key = oldKeys[i];
+    for (int key : oldKeys) {
       if (key == emptyVal) continue;
       int newSlot = getSlot(key);
       keys[newSlot] = key;