doc improvement

core/src/main/java/hudson/search/SearchIndex.java

@@ -26,7 +26,11 @@ package hudson.search;
 import java.util.List;
 
 /**
+ * Conceptually a set of {@link SearchItem}s that provide quick look-up
+ * from their {@linkplain SearchItem#getSearchName() names}.
+ *
  * @author Kohsuke Kawaguchi
+ * @see SearchIndexBuilder
  */
 public interface SearchIndex {
     void find(String token, List<SearchItem> result);

core/src/main/java/hudson/search/SearchIndexBuilder.java

@@ -23,11 +23,19 @@
  */
 package hudson.search;
 
+import hudson.model.AbstractModelObject;
+
 import java.util.ArrayList;
 import java.util.List;
 
 /**
+ * Builds {@link SearchIndex}.
+ *
+ * This object is also used to represent partially build search index, much like {@link StringBuilder} is often
+ * passed around to cooperatively build search index.
+ *
  * @author Kohsuke Kawaguchi
+ * @see AbstractModelObject#makeSearchIndex()
  */
 public final class SearchIndexBuilder {
     private final List<SearchItem> items = new ArrayList<SearchItem>();

core/src/main/java/hudson/search/SearchItem.java

@@ -57,6 +57,7 @@ public interface SearchItem {
      *
      * @return
      *      {@link SearchIndex#EMPTY} if this is a leaf.
+     * @see SearchIndexBuilder
      */
     SearchIndex getSearchIndex();
 }