diff --git a/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorManager.java b/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorManager.java
index 7e76b8a1d2d4..9ffed0e0960d 100644
--- a/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorManager.java
+++ b/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorManager.java
@@ -1,4 +1,4 @@
-// Copyright 2000-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
 package com.intellij.openapi.fileEditor;
 
 import com.intellij.openapi.Disposable;
@@ -32,7 +32,6 @@ public abstract class FileEditorManager {
    */
   public abstract FileEditor @NotNull [] openFile(@NotNull VirtualFile file, boolean focusEditor);
 
-
   /**
    * Opens a file.
    * Must be called from <a href="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html">EDT</a>.
@@ -46,7 +45,7 @@ public abstract class FileEditorManager {
   }
 
   /**
-   * Closes all editors opened for the file.
+   * Closes all the editors opened for a given file.
    * Must be called from <a href="https://docs.oracle.com/javase/tutorial/uiswing/concurrency/dispatch.html">EDT</a>.
    *
    * @param file file to be closed.
@@ -94,7 +93,7 @@ public abstract class FileEditorManager {
   public abstract boolean isFileOpen(@NotNull VirtualFile file);
 
   /**
-   * @return {@code true} if {@code file} is opened, {@code false} otherwise
+   * @return {@code true} if {@code file} is opened, {@code false} otherwise.
    * Unlike {@link #isFileOpen(VirtualFile)} includes files which were opened by all guests during a collaborative development session.
    */
   @ApiStatus.Experimental
@@ -108,10 +107,10 @@ public abstract class FileEditorManager {
   public abstract VirtualFile @NotNull [] getOpenFiles();
 
   /**
-   * @return all opened files including ones which were opened by guests during a collaborative development session.
-   * Order of files in the array corresponds to the order of host's editor tabs, order for guests isn't determined.
-   * There are cases when only editors for of a particular user is needed (e.g. a search scope 'open files'),
-   * but at the same time editor notifications should be shown to all users
+   * @return all opened files, including ones which were opened by guests during a collaborative development session.
+   * The order of files in the array corresponds to the order of host's editor tabs, order for guests isn't determined.
+   * There are cases when only editors of a particular user are needed (e.g. a search scope 'open files'),
+   * but at the same time editor notifications should be shown to all users.
    */
   @ApiStatus.Experimental
   public VirtualFile @NotNull [] getOpenFilesWithRemotes() {
@@ -123,18 +122,18 @@ public abstract class FileEditorManager {
   }
 
   /**
-   * @return files currently selected. The method returns empty array if there are no selected files.
-   * If more than one file is selected (split), the file with most recent focused editor is returned first.
+   * @return files currently selected. The method returns an empty array if there are no selected files.
+   * If more than one file is selected (split), the file with the most recent focused editor is returned first.
    */
   public abstract VirtualFile @NotNull [] getSelectedFiles();
 
   /**
-   * @return editors currently selected. The method returns empty array if no editors are open.
+   * @return editors currently selected. The method returns an empty array if no editors are open.
    */
   public abstract FileEditor @NotNull [] getSelectedEditors();
 
   /**
-   * @return editors currently selected including ones which were opened by guests during a collaborative development session
+   * @return editors currently selected including ones which were opened by guests during a collaborative development session.
    * The method returns an empty array if no editors are open.
    */
   @ApiStatus.Experimental
@@ -151,7 +150,7 @@ public abstract class FileEditorManager {
   }
 
   /**
-   * @return editor which is currently selected for given file.
+   * @return editor which is currently selected for a given file.
    * The method returns {@code null} if {@code file} is not opened.
    */
   public abstract @Nullable FileEditor getSelectedEditor(@NotNull VirtualFile file);
@@ -179,8 +178,8 @@ public abstract class FileEditorManager {
    * {@link com.intellij.openapi.editor.colors.EditorColors#SEPARATOR_ABOVE_COLOR SEPARATOR_ABOVE_COLOR} or
    * {@link com.intellij.openapi.editor.colors.EditorColors#TEARLINE_COLOR TEARLINE_COLOR} if it is not set.
    * <p>
-   * This method allows to add several components above the editor.
-   * To change an order of components the specified component may implement the
+   * This method allows adding several components above the editor.
+   * To change the order of components, the specified component may implement the
    * {@link com.intellij.openapi.util.Weighted Weighted} interface.
    */
   public abstract void addTopComponent(final @NotNull FileEditor editor, final @NotNull JComponent component);
@@ -195,8 +194,8 @@ public abstract class FileEditorManager {
    * {@link com.intellij.openapi.editor.colors.EditorColors#SEPARATOR_BELOW_COLOR SEPARATOR_BELOW_COLOR} or
    * {@link com.intellij.openapi.editor.colors.EditorColors#TEARLINE_COLOR TEARLINE_COLOR} if it is not set.
    * <p>
-   * This method allows to add several components below the editor.
-   * To change an order of components the specified component may implement the
+   * This method allows adding several components below the editor.
+   * To change the order of components, the specified component may implement the
    * {@link com.intellij.openapi.util.Weighted Weighted} interface.
    */
   public abstract void addBottomComponent(final @NotNull FileEditor editor, final @NotNull JComponent component);
@@ -208,7 +207,7 @@ public abstract class FileEditorManager {
   public static final Key<Color> SEPARATOR_COLOR = Key.create("FileEditorSeparatorColor");
 
   /**
-   * Adds specified {@code listener}
+   * Adds specified {@code listener}.
    *
    * @param listener listener to be added
    * @deprecated Use {@link com.intellij.util.messages.MessageBus} instead: see {@link FileEditorManagerListener#FILE_EDITOR_MANAGER}
@@ -218,7 +217,7 @@ public abstract class FileEditorManager {
   }
 
   /**
-   * Removes specified {@code listener}
+   * Removes specified {@code listener}.
    *
    * @param listener listener to be removed
    * @deprecated Use {@link FileEditorManagerListener#FILE_EDITOR_MANAGER} instead
@@ -239,9 +238,7 @@ public abstract class FileEditorManager {
   public abstract @NotNull List<FileEditor> openFileEditor(@NotNull FileEditorNavigatable descriptor, boolean focusEditor);
 
   /**
-   * Returns the project with which the file editor manager is associated.
-   *
-   * @return the project instance.
+   * @return the project which the file editor manager is associated with.
    */
   public abstract @NotNull Project getProject();
 
@@ -257,14 +254,13 @@ public abstract class FileEditorManager {
    * Selects a specified file editor tab for the specified editor.
    *
    * @param file                 a file to switch the file editor tab for. The function does nothing if the file is not currently open in the editor.
-   * @param fileEditorProviderId the ID of the file editor to open; matches the return value of
-   *                             {@link FileEditorProvider#getEditorTypeId()}
+   * @param fileEditorProviderId the ID of the file editor to open; matches the return value of {@link FileEditorProvider#getEditorTypeId()}
    */
   public abstract void setSelectedEditor(@NotNull VirtualFile file, @NotNull String fileEditorProviderId);
 
   /**
-   * {@link FileEditorManager} supports asynchronous opening of text editors, i.e. when one of 'openFile' methods returns, returned
-   * editor might not be fully initialized yet. This method allows delaying (if needed) execution of given runnable until editor is
+   * {@link FileEditorManager} supports asynchronous opening of text editors, i.e. when one of {@code openFile*} methods returns, returned
+   * editor might not be fully initialized yet. This method allows delaying (if needed) execution of a given runnable until the editor is
    * fully loaded.
    */
   public abstract void runWhenLoaded(@NotNull Editor editor, @NotNull Runnable runnable);
@@ -272,7 +268,7 @@ public abstract class FileEditorManager {
   /**
    * Refreshes the text, colors and icon of the editor tabs representing the specified file.
    *
-   * @param file the file to refresh.
+   * @param file refreshed file
    */
   public void updateFilePresentation(@NotNull VirtualFile file) { }
 }
diff --git a/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorManagerListener.java b/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorManagerListener.java
index aeaf3f80d96b..897b500bcff5 100644
--- a/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorManagerListener.java
+++ b/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorManagerListener.java
@@ -20,7 +20,7 @@ public interface FileEditorManagerListener extends EventListener {
   Topic<FileEditorManagerListener> FILE_EDITOR_MANAGER = new Topic<>(FileEditorManagerListener.class, Topic.BroadcastDirection.TO_PARENT);
 
   /**
-   * This method is called synchronously (in the same EDT event), as the creation of FileEditor(s).
+   * This method is called synchronously (in the same EDT event), as the creation of {@link FileEditor}s.
    *
    * @see #fileOpened(FileEditorManager, VirtualFile)
    * @deprecated use {@link #fileOpenedSync(FileEditorManager, VirtualFile, List)}
@@ -31,7 +31,7 @@ public interface FileEditorManagerListener extends EventListener {
   }
 
   /**
-   * This method is called synchronously (in the same EDT event), as the creation of FileEditor(s).
+   * This method is called synchronously (in the same EDT event), as the creation of {@link FileEditor}s.
    *
    * @see #fileOpened(FileEditorManager, VirtualFile)
    */
@@ -43,8 +43,8 @@ public interface FileEditorManagerListener extends EventListener {
   }
 
   /**
-   * This method is called after the focus settles down (if requested) in a newly created FileEditor.
-   * Be aware though, that this isn't always true in case of editors loaded asynchronously, which, in general,
+   * This method is called after the focus settles down (if requested) in a newly created {@link FileEditor}.
+   * Be aware that this isn't always true in the case of asynchronously loaded editors, which, in general,
    * may happen with any text editor. In that case, the focus request is postponed until after the editor is fully loaded,
    * which means that it may gain the focus way after this method is called.
    * When necessary, use {@link FileEditorManager#runWhenLoaded(Editor, Runnable)}) to ensure the desired ordering.
@@ -52,7 +52,7 @@ public interface FileEditorManagerListener extends EventListener {
    * {@link #fileOpenedSync(FileEditorManager, VirtualFile, List<FileEditorWithProvider>)} is always invoked before this method,
    * either in the same or the previous EDT event.
    *
-   * @see #fileOpenedSync(FileEditorManager, VirtualFile, List<FileEditorWithProvider>)}
+   * @see #fileOpenedSync(FileEditorManager, VirtualFile, List)
    */
   default void fileOpened(@NotNull FileEditorManager source, @NotNull VirtualFile file) {
   }
diff --git a/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorPolicy.java b/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorPolicy.java
index d56b6c538f5e..72a466466aaf 100644
--- a/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorPolicy.java
+++ b/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorPolicy.java
@@ -4,11 +4,9 @@ package com.intellij.openapi.fileEditor;
 public enum FileEditorPolicy {
 
   /**
-   * Place created editor before default IDE editor (if any).
-   */
-  /*
-   * should be the first declaration
+   * Place a created editor before the default IDE editor (if any).
    */
+  // should be the first declaration
   PLACE_BEFORE_DEFAULT_EDITOR,
 
   /**
@@ -24,8 +22,6 @@ public enum FileEditorPolicy {
   /**
    * Place created editor after the default IDE editor (if any).
    */
-  /*
-   * should be the last declaration
-   */
+  // should be the last declaration
   PLACE_AFTER_DEFAULT_EDITOR
 }
diff --git a/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorProvider.java b/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorProvider.java
index 75db1add993b..2688cada55f1 100644
--- a/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorProvider.java
+++ b/platform/analysis-api/src/com/intellij/openapi/fileEditor/FileEditorProvider.java
@@ -23,8 +23,9 @@ public interface FileEditorProvider {
   Key<FileEditorProvider> KEY = Key.create("com.intellij.fileEditorProvider");
 
   FileEditorProvider[] EMPTY_ARRAY = {};
+
   /**
-   * Method is expected to run fast.
+   * The method is expected to run fast.
    *
    * @param file file to be tested for acceptance.
    * @return {@code true} if provider can create valid editor for the specified {@code file}.
@@ -54,7 +55,7 @@ public interface FileEditorProvider {
   }
 
   /**
-   * Deserialize state from the specified {@code sourceElement}.
+   * Deserializes state from the specified {@code sourceElement}.
    */
   @NotNull
   default FileEditorState readState(@NotNull Element sourceElement, @NotNull Project project, @NotNull VirtualFile file) {
@@ -68,18 +69,19 @@ public interface FileEditorProvider {
   }
 
   /**
-   * @return id of type of the editors created with this FileEditorProvider. Each FileEditorProvider should have
-   * unique nonnull id. The id is used for saving/loading of EditorStates.
+   * @return editor type ID for the editors created with this FileEditorProvider. Each FileEditorProvider should have
+   * a unique nonnull ID. The ID is used for saving/loading of EditorStates.
    */
   @NotNull
   @NonNls
   String getEditorTypeId();
 
   /**
-   * @return policy that specifies how editor created via this provider should be opened.
+   * @return a policy that specifies how an editor created via this provider should be opened.
    * @see FileEditorPolicy#NONE
    * @see FileEditorPolicy#HIDE_DEFAULT_EDITOR
    * @see FileEditorPolicy#PLACE_BEFORE_DEFAULT_EDITOR
+   * @see FileEditorPolicy#PLACE_AFTER_DEFAULT_EDITOR
    */
   @NotNull
   FileEditorPolicy getPolicy();
diff --git a/platform/analysis-api/src/com/intellij/openapi/fileEditor/OpenFileDescriptor.java b/platform/analysis-api/src/com/intellij/openapi/fileEditor/OpenFileDescriptor.java
index 236cf459e7c2..d73415a93c94 100644
--- a/platform/analysis-api/src/com/intellij/openapi/fileEditor/OpenFileDescriptor.java
+++ b/platform/analysis-api/src/com/intellij/openapi/fileEditor/OpenFileDescriptor.java
@@ -1,4 +1,4 @@
-// Copyright 2000-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
 package com.intellij.openapi.fileEditor;
 
 import com.intellij.openapi.actionSystem.DataKey;
@@ -13,8 +13,8 @@ import org.jetbrains.annotations.NotNull;
  */
 public class OpenFileDescriptor implements FileEditorNavigatable, Comparable<OpenFileDescriptor> {
   /**
-   * Tells descriptor to navigate in specific editor rather than file editor in main IDE window.
-   * For example if you want to navigate in editor embedded into modal dialog, you should provide this data.
+   * Tells descriptor to navigate in specific editor rather than file editor in the main IDE window.
+   * For example, if you want to navigate in an editor embedded into modal dialog, you should provide this data.
    */
   public static final DataKey<Editor> NAVIGATE_IN_EDITOR = DataKey.create("NAVIGATE_IN_EDITOR");
 
diff --git a/platform/analysis-api/src/com/intellij/openapi/fileEditor/ex/FileEditorWithProvider.java b/platform/analysis-api/src/com/intellij/openapi/fileEditor/ex/FileEditorWithProvider.java
index 683460394bed..e2b89fe2c0ea 100644
--- a/platform/analysis-api/src/com/intellij/openapi/fileEditor/ex/FileEditorWithProvider.java
+++ b/platform/analysis-api/src/com/intellij/openapi/fileEditor/ex/FileEditorWithProvider.java
@@ -6,7 +6,7 @@ import com.intellij.openapi.fileEditor.FileEditorProvider;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * A holder for both {@link FileEditor} and {@link FileEditorProvider}
+ * A holder for both {@link FileEditor} and {@link FileEditorProvider}.
  * The package is suffixed with 'ex' for backward compatibility
  */
 public final class FileEditorWithProvider {
diff --git a/platform/editor-ui-api/src/com/intellij/openapi/fileEditor/FileEditor.java b/platform/editor-ui-api/src/com/intellij/openapi/fileEditor/FileEditor.java
index 1eebc0689d23..f65fc07d9d69 100644
--- a/platform/editor-ui-api/src/com/intellij/openapi/fileEditor/FileEditor.java
+++ b/platform/editor-ui-api/src/com/intellij/openapi/fileEditor/FileEditor.java
@@ -1,4 +1,4 @@
-// Copyright 2000-2021 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
 package com.intellij.openapi.fileEditor;
 
 import com.intellij.codeHighlighting.BackgroundEditorHighlighter;
@@ -47,7 +47,7 @@ public interface FileEditor extends UserDataHolder, Disposable {
 
   /**
    * Returns editor's name - a string that identifies the editor among others
-   * (e.g.: "GUI Designer" for graphical editing and "Text" for textual representation of a GUI form editors).
+   * (e.g.: "GUI Designer" for graphical editing and "Text" for textual representation of a GUI form editor).
    */
   @Nls(capitalization = Nls.Capitalization.Title) @NotNull String getName();
 
@@ -59,14 +59,14 @@ public interface FileEditor extends UserDataHolder, Disposable {
   }
 
   /**
-   * Applies given state to the editor.
+   * Applies a given state to the editor.
    */
   void setState(@NotNull FileEditorState state);
 
   /**
-   * In some cases, it's desirable to set state exactly as requested (e.g. on tab splitting), in other cases different behaviour is
-   * preferred, e.g. bringing caret into view on text editor opening. This method passes additional flag to FileEditor to indicate
-   * the desired way to set state.
+   * In some cases, it's desirable to set state exactly as requested (e.g. on tab splitting), while in other cases different behaviour is
+   * preferred, e.g. bringing caret into view on text editor opening.
+   * This method passes an additional flag to {@link FileEditor} to indicate the desired way to set state.
    */
   default void setState(@NotNull FileEditorState state, boolean exactState) {
     setState(state);
@@ -108,7 +108,7 @@ public interface FileEditor extends UserDataHolder, Disposable {
 
   /**
    * A highlighter object to perform background analysis and highlighting activities on.
-   * Return {@code null} if no background highlighting activity necessary for this file editor.
+   * Returns {@code null} if no background highlighting activity is necessary for this file editor.
    */
   default @Nullable BackgroundEditorHighlighter getBackgroundHighlighter() {
     return null;
@@ -128,7 +128,7 @@ public interface FileEditor extends UserDataHolder, Disposable {
   Key<VirtualFile> FILE_KEY = Key.create("FILE_KEY");
 
   /**
-   * Returns the file for which {@link FileEditorProvider#createEditor)} was called.
+   * Returns the file for which {@link FileEditorProvider#createEditor} was called.
    * The default implementation is temporary, and shall be dropped in the future.
    */
   default VirtualFile getFile() {
@@ -137,7 +137,7 @@ public interface FileEditor extends UserDataHolder, Disposable {
   }
 
   /**
-   * Returns the files for which {@link com.intellij.ide.SaveAndSyncHandler)} should be called on frame activation.
+   * Returns the files for which {@link com.intellij.ide.SaveAndSyncHandler} should be called on frame activation.
    */
   default @NotNull List<@NotNull VirtualFile> getFilesToRefresh() {
     VirtualFile file = getFile();