diff --git a/platform/diff-api/src/com/intellij/diff/DiffContext.java b/platform/diff-api/src/com/intellij/diff/DiffContext.java
index 536b2e5b19ef..4b59e20f1eeb 100644
--- a/platform/diff-api/src/com/intellij/diff/DiffContext.java
+++ b/platform/diff-api/src/com/intellij/diff/DiffContext.java
@@ -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) {
diff --git a/platform/diff-api/src/com/intellij/diff/DiffRequestFactory.java b/platform/diff-api/src/com/intellij/diff/DiffRequestFactory.java
index 79ae2f5f53b8..15e6f31bc515 100644
--- a/platform/diff-api/src/com/intellij/diff/DiffRequestFactory.java
+++ b/platform/diff-api/src/com/intellij/diff/DiffRequestFactory.java
@@ -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 {
diff --git a/platform/diff-api/src/com/intellij/diff/FrameDiffTool.java b/platform/diff-api/src/com/intellij/diff/FrameDiffTool.java
index 86f354889cc2..6523530397c7 100644
--- a/platform/diff-api/src/com/intellij/diff/FrameDiffTool.java
+++ b/platform/diff-api/src/com/intellij/diff/FrameDiffTool.java
@@ -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();
diff --git a/platform/diff-api/src/com/intellij/diff/SuppressiveDiffTool.java b/platform/diff-api/src/com/intellij/diff/SuppressiveDiffTool.java
index bb4a1bb898f8..668be3b18d40 100644
--- a/platform/diff-api/src/com/intellij/diff/SuppressiveDiffTool.java
+++ b/platform/diff-api/src/com/intellij/diff/SuppressiveDiffTool.java
@@ -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
diff --git a/platform/diff-api/src/com/intellij/diff/contents/DiffContent.java b/platform/diff-api/src/com/intellij/diff/contents/DiffContent.java
index 17782dde3b2f..73aecc968f50 100644
--- a/platform/diff-api/src/com/intellij/diff/contents/DiffContent.java
+++ b/platform/diff-api/src/com/intellij/diff/contents/DiffContent.java
@@ -36,8 +36,8 @@ public interface DiffContent {
   @Nullable
   OpenFileDescriptor getOpenFileDescriptor();
 
-  /*
-   * @See DiffRequest.onAssigned()
+  /**
+   * @see DiffRequest#onAssigned(boolean)
    */
   @CalledInAwt
   void onAssigned(boolean isAssigned);
diff --git a/platform/diff-api/src/com/intellij/diff/fragments/DiffFragment.java b/platform/diff-api/src/com/intellij/diff/fragments/DiffFragment.java
index a208a0b6aefc..c129de493cfc 100644
--- a/platform/diff-api/src/com/intellij/diff/fragments/DiffFragment.java
+++ b/platform/diff-api/src/com/intellij/diff/fragments/DiffFragment.java
@@ -15,6 +15,9 @@
  */
 package com.intellij.diff.fragments;
 
+/**
+ * Modified part of the text
+ */
 public interface DiffFragment {
   int getStartOffset1();
 
diff --git a/platform/diff-api/src/com/intellij/diff/fragments/LineFragment.java b/platform/diff-api/src/com/intellij/diff/fragments/LineFragment.java
index 1cb657e6ac74..7f8059815b82 100644
--- a/platform/diff-api/src/com/intellij/diff/fragments/LineFragment.java
+++ b/platform/diff-api/src/com/intellij/diff/fragments/LineFragment.java
@@ -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();
 
diff --git a/platform/diff-api/src/com/intellij/diff/merge/MergeContext.java b/platform/diff-api/src/com/intellij/diff/merge/MergeContext.java
index 6727d7e6eafd..148c74d81a7f 100644
--- a/platform/diff-api/src/com/intellij/diff/merge/MergeContext.java
+++ b/platform/diff-api/src/com/intellij/diff/merge/MergeContext.java
@@ -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) {
diff --git a/platform/diff-api/src/com/intellij/diff/merge/MergeRequest.java b/platform/diff-api/src/com/intellij/diff/merge/MergeRequest.java
index 3eb03a8a4495..5428bed24f43 100644
--- a/platform/diff-api/src/com/intellij/diff/merge/MergeRequest.java
+++ b/platform/diff-api/src/com/intellij/diff/merge/MergeRequest.java
@@ -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);
diff --git a/platform/diff-api/src/com/intellij/diff/merge/MergeTool.java b/platform/diff-api/src/com/intellij/diff/merge/MergeTool.java
index 86bc574a5ebd..0136e2bf9480 100644
--- a/platform/diff-api/src/com/intellij/diff/merge/MergeTool.java
+++ b/platform/diff-api/src/com/intellij/diff/merge/MergeTool.java
@@ -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;
   }
 }
diff --git a/platform/diff-api/src/com/intellij/diff/merge/ThreesideMergeRequest.java b/platform/diff-api/src/com/intellij/diff/merge/ThreesideMergeRequest.java
index 982402b26ba9..f47ede181f72 100644
--- a/platform/diff-api/src/com/intellij/diff/merge/ThreesideMergeRequest.java
+++ b/platform/diff-api/src/com/intellij/diff/merge/ThreesideMergeRequest.java
@@ -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
diff --git a/platform/diff-api/src/com/intellij/diff/requests/DiffRequest.java b/platform/diff-api/src/com/intellij/diff/requests/DiffRequest.java
index 2adddcf5c3cf..90eda329274b 100644
--- a/platform/diff-api/src/com/intellij/diff/requests/DiffRequest.java
+++ b/platform/diff-api/src/com/intellij/diff/requests/DiffRequest.java
@@ -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) {
diff --git a/platform/diff-impl/src/com/intellij/diff/impl/DiffViewerWrapper.java b/platform/diff-impl/src/com/intellij/diff/impl/DiffViewerWrapper.java
index bc7667324eae..657121fab339 100644
--- a/platform/diff-impl/src/com/intellij/diff/impl/DiffViewerWrapper.java
+++ b/platform/diff-impl/src/com/intellij/diff/impl/DiffViewerWrapper.java
@@ -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");
 
diff --git a/platform/diff-impl/src/com/intellij/diff/merge/TextMergeTool.java b/platform/diff-impl/src/com/intellij/diff/merge/TextMergeTool.java
index 2d1462edd615..4bef4e6374d2 100644
--- a/platform/diff-impl/src/com/intellij/diff/merge/TextMergeTool.java
+++ b/platform/diff-impl/src/com/intellij/diff/merge/TextMergeTool.java
@@ -155,6 +155,7 @@ public class TextMergeTool implements MergeTool {
       return myViewer.getPreferredFocusedComponent();
     }
 
+    @NotNull
     @Override
     public ToolbarComponents init() {
       ToolbarComponents components = new ToolbarComponents();
diff --git a/platform/diff-impl/src/com/intellij/diff/tools/util/FoldingModelSupport.java b/platform/diff-impl/src/com/intellij/diff/tools/util/FoldingModelSupport.java
index 859aa59a06fd..addf802d7f9e 100644
--- a/platform/diff-impl/src/com/intellij/diff/tools/util/FoldingModelSupport.java
+++ b/platform/diff-impl/src/com/intellij/diff/tools/util/FoldingModelSupport.java
@@ -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 = "     ";
diff --git a/platform/vcs-impl/src/com/intellij/openapi/vcs/changes/patch/ApplyPatchMergeTool.java b/platform/vcs-impl/src/com/intellij/openapi/vcs/changes/patch/ApplyPatchMergeTool.java
index 5458ebafd5ed..26a8bb6afa8a 100644
--- a/platform/vcs-impl/src/com/intellij/openapi/vcs/changes/patch/ApplyPatchMergeTool.java
+++ b/platform/vcs-impl/src/com/intellij/openapi/vcs/changes/patch/ApplyPatchMergeTool.java
@@ -86,6 +86,7 @@ public class ApplyPatchMergeTool implements MergeTool {
       return myViewer.getPreferredFocusedComponent();
     }
 
+    @NotNull
     @Override
     public ToolbarComponents init() {
       final Project project = myMergeContext.getProject();