diff --git a/platform/vcs-log/api/src/com/intellij/vcs/log/VcsLogDiffHandler.java b/platform/vcs-log/api/src/com/intellij/vcs/log/VcsLogDiffHandler.java
index f334465a062f..24dd4441878a 100644
--- a/platform/vcs-log/api/src/com/intellij/vcs/log/VcsLogDiffHandler.java
+++ b/platform/vcs-log/api/src/com/intellij/vcs/log/VcsLogDiffHandler.java
@@ -20,11 +20,34 @@ import com.intellij.openapi.vfs.VirtualFile;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Enables showing diff between revisions and comparing file or directory state between a revision and a local version in log-based file history.
+ * Methods of this class could be called from EDT, so it should deal with it appropriately by starting a background task for long operations,
+ * eg for loading revisions content.
+ */
 public interface VcsLogDiffHandler {
+
+  /**
+   * Show diff between (the after-state of) two revisions in the specified files or directories.
+   *
+   * @param root      repository root.
+   * @param leftPath  path to the file on the left, null means file is missing in this revision.
+   * @param leftHash  hash of the revision on the left.
+   * @param rightPath path to the file on the right, null means file is missing in this revision.
+   * @param rightHash hash of the revision on the right.
+   */
   void showDiff(@NotNull VirtualFile root,
                 @Nullable FilePath leftPath, @NotNull Hash leftHash,
                 @Nullable FilePath rightPath, @NotNull Hash rightHash);
 
+  /**
+   * Show diff between (the after-state of) specified revision and local version for the specified file or directory.
+   *
+   * @param root         repository root.
+   * @param revisionPath path to the file in the specified revision, null means file is not present in the revision.
+   * @param hash         hash of the revision.
+   * @param localPath    local path to the file.
+   */
   void showDiffWithLocal(@NotNull VirtualFile root,
                          @Nullable FilePath revisionPath,
                          @NotNull Hash hash, @NotNull FilePath localPath);
diff --git a/platform/vcs-log/api/src/com/intellij/vcs/log/VcsLogProvider.java b/platform/vcs-log/api/src/com/intellij/vcs/log/VcsLogProvider.java
index 6e001856eb36..f17de3d09285 100644
--- a/platform/vcs-log/api/src/com/intellij/vcs/log/VcsLogProvider.java
+++ b/platform/vcs-log/api/src/com/intellij/vcs/log/VcsLogProvider.java
@@ -147,6 +147,11 @@ public interface VcsLogProvider {
   @Nullable
   String getCurrentBranch(@NotNull VirtualFile root);
 
+  /**
+   * Returns {@link VcsLogDiffHandler} for this provider in order to support comparing commits and with local version from log-based file history.
+   *
+   * @return diff handler or null if unsupported.
+   */
   @Nullable
   VcsLogDiffHandler getDiffHandler();