diff: improve javadoc for DiffRequestChain
authorAleksey Pivovarov <AMPivovarov@gmail.com>
Mon, 23 May 2022 10:38:46 +0000 (12:38 +0200)
committerintellij-monorepo-bot <intellij-monorepo-bot-no-reply@jetbrains.com>
Mon, 23 May 2022 11:30:09 +0000 (11:30 +0000)
GitOrigin-RevId: 88057d6861d6b751d7f1209c63f0b5c48b32ff37

platform/diff-api/src/com/intellij/diff/chains/DiffRequestChain.java
platform/diff-api/src/com/intellij/diff/chains/SimpleDiffRequestChain.java
platform/diff-impl/src/com/intellij/diff/chains/AsyncDiffRequestChain.java
platform/vcs-impl/src/com/intellij/openapi/vcs/changes/ui/ChangeDiffRequestChain.java

index 53663dec174d52a8dfcee4e522ac66f1aec51e76..46e4a9a4b1ef5488ecbde8995df05ea2f8de3af8 100644 (file)
@@ -10,17 +10,21 @@ import org.jetbrains.annotations.NotNull;
 import java.util.List;
 
 /**
 import java.util.List;
 
 /**
- * Represents list of changed files (ex: singular commit).
+ * Represents list of changed files (ex: singular commit).
  * The list is not supposed to be changed and can be shown multiple times.
  * <p>
  * The list is not supposed to be changed and can be shown multiple times.
  * <p>
- * Use {@link AsyncDiffRequestChain} to load requests asynchronously after showing UI
- * Use {@link com.intellij.openapi.vcs.changes.ui.ChangeDiffRequestChain} for chains with common "Go to change" navigation popup.
+ * Use {@link SimpleDiffRequestChain} and {@link com.intellij.openapi.vcs.changes.ui.ChangeDiffRequestChain} as typical implementations.
+ * <p>
+ * Use {@link AsyncDiffRequestChain} instead if loading the list of changed files is a slow operation
  *
  * @see DiffRequestSelectionChain
  * @see com.intellij.diff.DiffManager#showDiff(Project, DiffRequestChain, DiffDialogHints)
  * @see com.intellij.diff.impl.CacheDiffRequestChainProcessor
  */
 public interface DiffRequestChain extends UserDataHolder {
  *
  * @see DiffRequestSelectionChain
  * @see com.intellij.diff.DiffManager#showDiff(Project, DiffRequestChain, DiffDialogHints)
  * @see com.intellij.diff.impl.CacheDiffRequestChainProcessor
  */
 public interface DiffRequestChain extends UserDataHolder {
+  /**
+   * NB: if you're calling this method for an unknown chain type, you should be ready to handle {@link AsyncDiffRequestChain}.
+   */
   @NotNull
   @RequiresEdt
   List<? extends DiffRequestProducer> getRequests();
   @NotNull
   @RequiresEdt
   List<? extends DiffRequestProducer> getRequests();
index 6a3675b889bc716086c88b7503d81f3596d36317..a1efb9c0b4961e36d58b19e093dcf547f915f323 100644 (file)
@@ -37,7 +37,11 @@ public class SimpleDiffRequestChain extends UserDataHolderBase implements DiffRe
   }
 
   public SimpleDiffRequestChain(@NotNull List<? extends DiffRequest> requests) {
   }
 
   public SimpleDiffRequestChain(@NotNull List<? extends DiffRequest> requests) {
-    myRequests = ListSelection.createAt(requests, 0).map(request -> new DiffRequestProducerWrapper(request));
+    this(requests, 0);
+  }
+
+  public SimpleDiffRequestChain(@NotNull List<? extends DiffRequest> requests, int selectedIndex) {
+    myRequests = ListSelection.createAt(requests, selectedIndex).map(request -> new DiffRequestProducerWrapper(request));
   }
 
   private SimpleDiffRequestChain(@NotNull ListSelection<? extends DiffRequestProducer> requests, @Nullable Object constructorFlag) {
   }
 
   private SimpleDiffRequestChain(@NotNull ListSelection<? extends DiffRequestProducer> requests, @Nullable Object constructorFlag) {
index e3dbdaf516d9984430d17ec454679c39da5e05a1..37b53da57d424e39158747d456df46639548fe72 100644 (file)
@@ -17,6 +17,11 @@ import org.jetbrains.annotations.Nullable;
 
 import java.util.EventListener;
 
 
 import java.util.EventListener;
 
+/**
+ * Allows loading requests asynchronously after showing diff UI, without the need for modal progress
+ *
+ * @see com.intellij.openapi.vcs.changes.ui.ChangeDiffRequestChain.Async
+ */
 public abstract class AsyncDiffRequestChain extends UserDataHolderBase implements DiffRequestSelectionChain {
   private final EventDispatcher<Listener> myDispatcher = EventDispatcher.create(Listener.class);
 
 public abstract class AsyncDiffRequestChain extends UserDataHolderBase implements DiffRequestSelectionChain {
   private final EventDispatcher<Listener> myDispatcher = EventDispatcher.create(Listener.class);
 
index 1dd5cdd895bbc9295ddb05cea7ee5f8e2ff98cef..e0ff4a4234fb5e658bd9af26a64a1ab2892909f3 100644 (file)
@@ -21,6 +21,11 @@ import org.jetbrains.annotations.Nullable;
 import java.util.ArrayList;
 import java.util.List;
 
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Supports typical tree-like "Go to Change" navigation popup.
+ *
+ * @see ChangeDiffRequestChain.Async
+ */
 public class ChangeDiffRequestChain extends UserDataHolderBase implements DiffRequestSelectionChain, GoToChangePopupBuilder.Chain {
   private static final Logger LOG = Logger.getInstance(ChangeDiffRequestChain.class);
   @NotNull private final ListSelection<? extends Producer> myProducers;
 public class ChangeDiffRequestChain extends UserDataHolderBase implements DiffRequestSelectionChain, GoToChangePopupBuilder.Chain {
   private static final Logger LOG = Logger.getInstance(ChangeDiffRequestChain.class);
   @NotNull private final ListSelection<? extends Producer> myProducers;