From f41e0fedfa057b3a6aa0c50fa2537e285c177a87 Mon Sep 17 00:00:00 2001 From: Karol Lewandowski Date: Mon, 11 Apr 2022 14:23:34 +0200 Subject: [PATCH] File Editor and related classes docs polishing and links fixes GitOrigin-RevId: eb3ba7c0b665d69ac59d73afac27c4fd197d7a1d --- .../openapi/fileEditor/FileEditorManager.java | 50 +++++++++---------- .../fileEditor/FileEditorManagerListener.java | 10 ++-- .../openapi/fileEditor/FileEditorPolicy.java | 10 ++-- .../fileEditor/FileEditorProvider.java | 12 +++-- .../fileEditor/OpenFileDescriptor.java | 6 +-- .../fileEditor/ex/FileEditorWithProvider.java | 2 +- .../openapi/fileEditor/FileEditor.java | 18 +++---- 7 files changed, 51 insertions(+), 57 deletions(-) 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 EDT. @@ -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 EDT. * * @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. *

- * 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. *

- * 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 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 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 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)} is always invoked before this method, * either in the same or the previous EDT event. * - * @see #fileOpenedSync(FileEditorManager, VirtualFile, List)} + * @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 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 { /** - * 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 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 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();