diff: javadoc

2026-09-27 10:03:11 +07:00 · 2015-09-16 14:34:25 +03:00
parent d6312f1e59
commit e3379d6783
16 changed files with 75 additions and 14 deletions
@@ -30,10 +30,22 @@ public abstract class DiffContext implements UserDataHolder {

  public abstract boolean isWindowFocused();

+  /**
+   * @return whether diff panel holds focus
+   */
  public abstract boolean isFocused();

+  /**
+   * Request focus on diff panel ({@link FrameDiffTool.DiffViewer#getPreferredFocusedComponent()} in current viewer)
+   * NB: focus requested via {@link java.awt.Component#requestFocus()}, ignoring {@link com.intellij.openapi.wm.IdeFocusManager}
+   * <p/>
+   * This method can be used in pair with {@link #isFocused()} to keep focus on modifications of component tree
+   */
  public abstract void requestFocus();

+  /**
+   * @see com.intellij.diff.util.DiffUserDataKeys
+   */
  @Nullable
  @Override
  public <T> T getUserData(@NotNull Key<T> key) {
@@ -30,7 +30,7 @@ import org.jetbrains.annotations.Nullable;

 import java.util.List;

-/*
+/**
 * Use ProgressManager.executeProcessUnderProgress() to pass modality state if needed
 */
 public abstract class DiffRequestFactory {
@@ -26,6 +26,9 @@ import javax.swing.*;
 import java.util.List;

 public interface FrameDiffTool extends DiffTool {
+  /**
+   * Creates viewer for the given request. Clients should call {@link #canShow(DiffContext, DiffRequest)} first.
+   */
  @CalledInAwt
  @NotNull
  DiffViewer createComponent(@NotNull DiffContext context, @NotNull DiffRequest request);
@@ -37,6 +40,9 @@ public interface FrameDiffTool extends DiffTool {
    @Nullable
    JComponent getPreferredFocusedComponent();

+    /**
+     * Should be called after adding {@link #getComponent()} to the components hierarchy.
+     */
    @NotNull
    @CalledInAwt
    ToolbarComponents init();
@@ -17,7 +17,7 @@ package com.intellij.diff;

 import java.util.List;

-/*
+/**
 * Allows to remove other DiffTools from list of available if current one can show request.
 *
 * 4ex: this could be used by 'image comparator plugin' to hide default binary diff tool
@@ -36,8 +36,8 @@ public interface DiffContent {
  @Nullable
  OpenFileDescriptor getOpenFileDescriptor();

-  /*
-   * @See DiffRequest.onAssigned()
+  /**
+   * @see DiffRequest#onAssigned(boolean)
   */
  @CalledInAwt
  void onAssigned(boolean isAssigned);
@@ -15,6 +15,9 @@
 */
 package com.intellij.diff.fragments;

+/**
+ * Modified part of the text
+ */
 public interface DiffFragment {
  int getStartOffset1();

@@ -19,6 +19,11 @@ import org.jetbrains.annotations.Nullable;

 import java.util.List;

+/**
+ * Modified part of the text
+ *
+ * Offset ranges cover whole line, including '\n' at the end. But '\n' can be absent for the last line.
+ */
 public interface LineFragment extends DiffFragment {
  int getStartLine1();

@@ -33,9 +33,15 @@ public abstract class MergeContext implements UserDataHolder {

  public abstract void requestFocus();

+  /**
+   * Called by MergeTool on conflict resolve end. Should delegate to the {@link MergeRequest#applyResult(MergeResult)}
+   */
  @CalledInAwt
  public abstract void finishMerge(@NotNull MergeResult result);

+  /**
+   * @see com.intellij.diff.util.DiffUserDataKeys
+   */
  @Nullable
  @Override
  public <T> T getUserData(@NotNull Key<T> key) {
@@ -28,8 +28,10 @@ public abstract class MergeRequest implements UserDataHolder {
  @Nullable
  public abstract String getTitle();

-  /*
-   * Called on conflict resolve end.
+  /**
+   * Called on conflict resolve end. Should be called exactly once for each request, that was shown.
+   *
+   * MergeRequest should keep initial state of its content and restore it on {@link MergeResult.CANCEL}
   */
  @CalledInAwt
  public abstract void applyResult(@NotNull MergeResult result);
@@ -29,16 +29,19 @@ import java.util.List;
 public interface MergeTool {
  ExtensionPointName<MergeTool> EP_NAME = ExtensionPointName.create("com.intellij.diff.merge.MergeTool");

+  /**
+   * Creates viewer for the given request. Clients should call {@link #canShow(MergeContext, MergeRequest)} first.
+   */
  @CalledInAwt
  @NotNull
  MergeViewer createComponent(@NotNull MergeContext context, @NotNull MergeRequest request);

  boolean canShow(@NotNull MergeContext context, @NotNull MergeRequest request);

-  /*
-   * Merge viewer should call MergeContext.finishMerge(MergeResult) when processing is over.
+  /**
+   * Merge viewer should call {@link MergeContext#finishMerge(MergeResult)} when processing is over.
   *
-   * MergeRequest.applyResult() will be performed by the caller, so it shouldn't be called by MergeViewer directly.
+   * {@link MergeRequest#applyResult(MergeResult)} will be performed by the caller, so it shouldn't be called by MergeViewer directly.
   */
  interface MergeViewer extends Disposable {
    @NotNull
@@ -47,9 +50,20 @@ public interface MergeTool {
    @Nullable
    JComponent getPreferredFocusedComponent();

+    /**
+     * @return Action that should be triggered on the corresponding action.
+     * <p/>
+     * Typical implementation can perform some checks and either call finishMerge(result) or do nothing
+     * <p/>
+     * return null if action is not available
+     */
    @Nullable
    Action getResolveAction(@NotNull MergeResult result);

+    /**
+     * Should be called after adding {@link #getComponent()} to the components hierarchy.
+     */
+    @NotNull
    @CalledInAwt
    ToolbarComponents init();

@@ -61,6 +75,10 @@ public interface MergeTool {
  class ToolbarComponents {
    @Nullable public List<AnAction> toolbarActions;
    @Nullable public JComponent statusPanel;
-    @Nullable public BooleanGetter closeHandler; // return false if merge window should be prevented from closing and canceling resolve.
+
+    /**
+     * return false if merge window should be prevented from closing and canceling resolve.
+     */
+    @Nullable public BooleanGetter closeHandler;
  }
 }
@@ -16,13 +16,12 @@
 package com.intellij.diff.merge;

 import com.intellij.diff.contents.DiffContent;
-import org.jetbrains.annotations.CalledInAwt;
 import org.jetbrains.annotations.NotNull;

 import java.util.List;

 public abstract class ThreesideMergeRequest extends MergeRequest {
-  /*
+  /**
   * 3 contents: left - middle - right (local - base - server)
   */
  @NotNull
@@ -41,6 +41,9 @@ public abstract class DiffRequest implements UserDataHolder {
  public void onAssigned(boolean isAssigned) {
  }

+  /**
+   * @see com.intellij.diff.util.DiffUserDataKeys
+   */
  @Nullable
  @Override
  public <T> T getUserData(@NotNull Key<T> key) {
@@ -21,6 +21,11 @@ import com.intellij.diff.requests.DiffRequest;
 import com.intellij.openapi.util.Key;
 import org.jetbrains.annotations.NotNull;

+/*
+ * This is not an extension point you are looking for.
+ * <p/>
+ * Please, consider using DiffTool, DiffExtension or introducing a better extension point instead.
+ */
 public interface DiffViewerWrapper {
  Key<DiffViewerWrapper> KEY = Key.create("Diff.DiffViewerWrapper");

@@ -155,6 +155,7 @@ public class TextMergeTool implements MergeTool {
      return myViewer.getPreferredFocusedComponent();
    }

+    @NotNull
    @Override
    public ToolbarComponents init() {
      ToolbarComponents components = new ToolbarComponents();
@@ -48,12 +48,12 @@ import java.util.Iterator;
 import java.util.List;
 import java.util.Set;

-/*
+/**
 * This class allows to add custom foldings to hide unchanged regions in diff.
 * EditorSettings#isAutoCodeFoldingEnabled() should be true, to avoid collisions with language-specific foldings
 *    (as it's impossible to create partially overlapped folding regions)
- * @See DiffUtil.setFoldingModelSupport()
 *
+ * @see DiffUtil#setFoldingModelSupport(EditorEx)
 */
 public class FoldingModelSupport {
  public static final String PLACEHOLDER = "     ";
@@ -86,6 +86,7 @@ public class ApplyPatchMergeTool implements MergeTool {
      return myViewer.getPreferredFocusedComponent();
    }

+    @NotNull
    @Override
    public ToolbarComponents init() {
      final Project project = myMergeContext.getProject();