From b363b4d64efb1e548ed9949e46b07019298bc6d9 Mon Sep 17 00:00:00 2001
From: peter <peter@jetbrains.com>
Date: Wed, 5 Apr 2017 15:43:53 +0200
Subject: [PATCH] document CompletionResultSet.addAllElements batch processing
 semantics

---
 .../codeInsight/completion/CompletionResultSet.java | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/platform/lang-api/src/com/intellij/codeInsight/completion/CompletionResultSet.java b/platform/lang-api/src/com/intellij/codeInsight/completion/CompletionResultSet.java
index 8d00c6d3ce46..6742bed18b5b 100644
--- a/platform/lang-api/src/com/intellij/codeInsight/completion/CompletionResultSet.java
+++ b/platform/lang-api/src/com/intellij/codeInsight/completion/CompletionResultSet.java
@@ -62,7 +62,8 @@ public abstract class CompletionResultSet implements Consumer<LookupElement> {
   }
 
   /**
-   * If a given element matches the prefix, give it for further processing (which may eventually result in its appearing in the completion list)
+   * If a given element matches the prefix, give it for further processing (which may eventually result in its appearing in the completion list).
+   * @see #addAllElements(Iterable) 
    */
   public abstract void addElement(@NotNull final LookupElement element);
 
@@ -70,6 +71,16 @@ public abstract class CompletionResultSet implements Consumer<LookupElement> {
     myConsumer.consume(result);
   }
 
+  /**
+   * Adds all elements from the given collection that match the prefix for further processing. The elements are processed in batch,
+   * so that they'll appear in lookup all together.<p/>
+   * This can be useful to ensure predictable order of top suggested elements.
+   * Otherwise, when the lookup is shown, most relevant elements processed to that moment are put to the top 
+   * and remain there even if more relevant elements appear later. 
+   * These "first" elements may differ from completion invocation to completion invocation due to performance fluctuations,
+   * resulting in varying preselected item in completion and worse user experience. Using {@code addAllElements} 
+   * instead of {@link #addElement(LookupElement)} helps to avoid that.
+   */
   public void addAllElements(@NotNull final Iterable<? extends LookupElement> elements) {
     int seldomCounter = 0;
     for (LookupElement element : elements) {