From 099f981df7e9d486d39f0d9788d6930fd8e47826 Mon Sep 17 00:00:00 2001 From: Karol Lewandowski Date: Mon, 28 Feb 2022 13:08:47 +0100 Subject: [PATCH] minor grammar fixes and cleanups --- .../getting_started/deploying_plugin.md | 4 +- .../file_based_indexes.md | 26 +++---- .../external_builder_api.md | 8 +-- topics/reference_guide/intellij_artifacts.md | 4 +- .../working_with_custom_actions.md | 22 ++++-- .../reference_contributor.md | 2 +- topics/tutorials/framework.md | 68 +++++++++---------- 7 files changed, 73 insertions(+), 61 deletions(-) diff --git a/topics/basics/getting_started/deploying_plugin.md b/topics/basics/getting_started/deploying_plugin.md index 5a67f6217..288c3a2a7 100644 --- a/topics/basics/getting_started/deploying_plugin.md +++ b/topics/basics/getting_started/deploying_plugin.md @@ -12,8 +12,8 @@ To deploy a plugin: ![Prepare Plugin for Deployment](prepare_plugin_for_deployment.png) -* If the plugin module does not depend on any libraries, a `.jar` archive will be created. - Otherwise, a `.zip` archive will be created, including all the plugin libraries specified in the project settings. +* If the plugin module does not depend on any libraries, a JAR archive will be created. + Otherwise, a ZIP archive will be created, including all the plugin libraries specified in the project settings. ![Jar Saved Notification](jar_saved_notification.png) diff --git a/topics/basics/indexing_and_psi_stubs/file_based_indexes.md b/topics/basics/indexing_and_psi_stubs/file_based_indexes.md index 5dae13c96..597f2afc2 100644 --- a/topics/basics/indexing_and_psi_stubs/file_based_indexes.md +++ b/topics/basics/indexing_and_psi_stubs/file_based_indexes.md @@ -18,7 +18,7 @@ In the simplest case, when one needs to know in what files some data is present, When the index implementation indexes a file, it receives a file's content and returns a map from the keys found in the file to the associated values. When accessing an index, specify the key you're interested in and get back the list of files in which the key occurs, and the value associated with each file. - + > In some cases, using [Gists](indexing_and_psi_stubs.md#gists) can be considered as an alternative. > {type="tip"} @@ -46,17 +46,17 @@ In case of single value per file, extend from [`SingleEntryFileBasedIndexExtensi Please see also [Improving indexing performance](performance.md#improving-indexing-performance). - > **Critical Implementation Notes** - > - > Value class must implement `equals()` and `hashCode()` properly, so a value deserialized from binary data should be equal to original one. - > - > The data returned by `DataIndexer.map()` must depend only on input data passed to the method, and must not depend on any external files. - > Otherwise, your index will not be correctly updated when the external data changes, and you will have stale data in your index. - > - > Please set system property `intellij.idea.indices.debug`/`intellij.idea.indices.debug.extra.sanity` to `true` to enable additional debugging assertions during development to assert correct index implementation. - > - {type="warning"} - +> **Critical Implementation Notes** +> +> Value class must implement `equals()` and `hashCode()` properly, so a value deserialized from binary data should be equal to original one. +> +> The data returned by `DataIndexer.map()` must depend only on input data passed to the method, and must not depend on any external files. +> Otherwise, your index will not be correctly updated when the external data changes, and you will have stale data in your index. +> +> Please set system property `intellij.idea.indices.debug`/`intellij.idea.indices.debug.extra.sanity` to `true` to enable additional debugging assertions during development to assert correct index implementation. +> +{type="warning"} + ## Accessing a File-Based Index Access to file-based indexes is performed through the [`FileBasedIndex`](upsource:///platform/indexing-api/src/com/intellij/util/indexing/FileBasedIndex.java) class. @@ -96,7 +96,7 @@ Generally, the word index should be accessed indirectly by using helper methods ### File Type Index [`FileTypeIndex`](upsource:///platform/indexing-api/src/com/intellij/psi/search/FileTypeIndex.java) serves a similar goal: it allows to find all files of a particular [`FileType`](upsource:///platform/core-api/src/com/intellij/openapi/fileTypes/FileType.java) quickly. - + ## Additional Index Roots To add additional files/directories to be indexed, implement [`IndexableSetContributor`](upsource:///platform/indexing-api/src/com/intellij/util/indexing/IndexableSetContributor.java) and register in [`com.intellij.indexedRootsProvider`](https://jb.gg/ipe?extensions=com.intellij.indexedRootsProvider) extension point. diff --git a/topics/reference_guide/frameworks_and_external_apis/external_builder_api.md b/topics/reference_guide/frameworks_and_external_apis/external_builder_api.md index 8d7487eb7..089c44ec8 100644 --- a/topics/reference_guide/frameworks_and_external_apis/external_builder_api.md +++ b/topics/reference_guide/frameworks_and_external_apis/external_builder_api.md @@ -53,8 +53,8 @@ These files don't have extensions, so you need to map corresponding patterns to Sources of a plugin for External Builder should be put in a separate module. By convention, such a module has a name '...-jps-plugin', and its sources are placed under the 'jps-plugin' directory in the main plugin directory. -Use `com.intellij.compileServer.plugin` extension to add the plugin to the classpath of the external build process, the plugin jar should be named `.jar`. 'Build' \| 'Prepare Plugin Module for deployment' action will automatically pack the 'jps-plugin' part to a separate jar accordingly. - +Use `com.intellij.compileServer.plugin` extension to add the plugin to the classpath of the external build process, the plugin JAR should be named `.jar`. 'Build' \| 'Prepare Plugin Module for deployment' action will automatically pack the 'jps-plugin' part to a separate JAR accordingly. + See [IntelliJ Platform Explorer](https://jb.gg/ipe?extensions=com.intellij.compileServer.plugin) for samples. ### Debugging a Plugin for External Builder @@ -62,7 +62,7 @@ See [IntelliJ Platform Explorer](https://jb.gg/ipe?extensions=com.intellij.compi **If your test IDE is IntelliJ IDEA 16.0 or newer** Switch on "Debug Build Process" toggle action (available via 'Find Action') in the test IDE. -After that every time compilation is run, the build process will wait for debugger connection on some (random) port and will show the port number in the status bar. +After that, every time compilation is run, the build process will wait for debugger connection on some (random) port and will show the port number in the status bar. In a working copy of IDE, a "Remote" run configuration should be created and pointed to this port. Suppose you often need to debug external builders and want to reuse the created "Remote" run configuration. In that case, you may fix the port number by adding the following VM option to the plugin run configuration: @@ -89,7 +89,7 @@ To enable them do the following: 1. Copy `/lib/yjp-controller-api-redist.jar` and `/bin/yjpagent.*` files to `/compile-server` 2. In "Settings \| Compiler \| Additional compiler process VM options" field enter `-Dprofiling.mode=true` -3. Make sure automatic make is turned off +3. Make sure the automatic make is turned off After this, every build process run should result in a CPU snapshot stored in ``/Snapshots directory. Snapshots are named like "ExternalBuild\-\{date\}.snapshot". diff --git a/topics/reference_guide/intellij_artifacts.md b/topics/reference_guide/intellij_artifacts.md index c8568fc10..c98140310 100644 --- a/topics/reference_guide/intellij_artifacts.md +++ b/topics/reference_guide/intellij_artifacts.md @@ -35,7 +35,7 @@ A link to this repository should be added to pom.xml/build.gr IntelliJ Platform module artifacts are utilized by adding information to a project's build.gradle file. More information about [Gradle support](https://www.jetbrains.com/help/idea/gradle.html) is available in the IntelliJ IDEA Help documentation. -To setup dependencies on a module there are two types of information needed: +To set up dependencies on a module, there are two types of information needed: 1. Specify the corresponding repository URL for the artifact. 2. Specify the [Maven coordinates](https://maven.apache.org/pom.html#Maven_Coordinates) for the artifact. @@ -94,7 +94,7 @@ The example illustrates declaring the artifact URL, Maven coordinates, and versi There are two parts to the example: the repository and the dependency sections. ### Repositories Section -This code snippet selects the release repository with the first URL, and repository of IntelliJ Platform dependencies with the second URL. +This code snippet selects the release repository with the first URL, and the repository of IntelliJ Platform dependencies with the second URL. The second URL is needed because this example selects individual modules. ```groovy diff --git a/topics/tutorials/action_system/working_with_custom_actions.md b/topics/tutorials/action_system/working_with_custom_actions.md index 0e1f75118..656645014 100644 --- a/topics/tutorials/action_system/working_with_custom_actions.md +++ b/topics/tutorials/action_system/working_with_custom_actions.md @@ -3,6 +3,7 @@ ## Introduction + Plugins can add actions to existing IDE menus and toolbars, as well as add new menus and toolbars. The IntelliJ Platform calls the actions of plugins in response to user interactions with the IDE. However, the actions of a plugin must first be defined and registered with the IntelliJ Platform. @@ -10,6 +11,7 @@ However, the actions of a plugin must first be defined and registered with the I Using the SDK code sample `action_basics`, this tutorial illustrates the steps to create an action for a plugin. ## Creating a Custom Action + Custom actions extend the abstract class [`AnAction`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java). Classes that extend it should override `AnAction.update()`, and must override `AnAction.actionPerformed()`. * The `update()` method implements the code that enables or disables an action. @@ -33,11 +35,11 @@ public class PopupDialogAction extends AnAction { } ``` - > `AnAction` classes do not have class fields of any kind. +> `AnAction` classes do not have class fields of any kind. > This restriction prevents memory leaks. > For more information about why, see [Action Implementation](basic_action_system.md#action-implementation). - > - {type="warning"} +> +{type="warning"} At this stage, `update()` implicitly defaults always to enable this action. The implementation of `actionPerformed()` does nothing. @@ -46,11 +48,13 @@ These methods fully implemented in [Developing the AnAction Methods](#developing Before fleshing out those methods, to complete this minimal implementation, `PopupDialogAction` must be registered with the IntelliJ Platform. ## Registering a Custom Action + Actions are registered by declaring them in code or by declaring them in the `` section of a plugin configuration (plugin.xml) file. This section describes using IDE tooling - the New Action Form - to add a declaration to the plugin.xml file, and then tuning registration attributes manually. A more comprehensive explanation of action registration is available in the [Action Registration](basic_action_system.md#registering-actions) section of this guide. ### Registering an Action with the New Action Form + IntelliJ IDEA has an embedded inspection that spots unregistered actions. Verify the inspection is enabled at Settings/Preferences | Editor | Inspections | Plugin DevKit | Code | Component/Action not registered. Here is an example for this stage of the `PopupDialogAction` class: @@ -87,12 +91,13 @@ After finishing the **New Action** form and applying the changes, the ` ``` -The `` element declares the _Action ID_ (`id`,) _Class Name_ (`class`,) _Name_ (`text`,) and _Description_ from the **New Action** form. +The `` element declares the _Action ID_ (`id`), _Class Name_ (`class`), _Name_ (`text`), and _Description_ from the **New Action** form. The `` element declares where the action will appear and mirrors the names of entries from the form. This declaration is adequate, but adding more attributes is discussed in the next section. ### Setting Registration Attributes Manually + An action declaration can be added manually to the plugin.xml file. An exhaustive list of declaration elements and attributes is presented in [Registering Actions in plugin.xml](basic_action_system.md#registering-actions-in-pluginxml). Attributes are added by selecting them from the **New Action** form, or by editing the registration declaration directly in the plugin.xml file. @@ -113,12 +118,14 @@ The full declaration is: ``` #### Using Override-Text for an Action + By using the `override-text` element introduced in 2020.1 of the IntelliJ Platform, the action text can be different depending on the context of where the action appears: menu, toolbar, etc. The example above uses this element to ensure the shorter text "Pop Dialog Action" is shown anywhere the action appears in the Main Menu structure. Otherwise, the default, more explanatory text "Action Basics Plugin: Pop Dialog Action" is shown. For more information, see [Setting the Override-Text Element](basic_action_system.md#setting-the-override-text-element). ## Testing the Minimal Custom Action Implementation + After performing the steps described above, compile and run the plugin to see the newly created action available as a Tools Menu item, which is within the context of the Main Menu: !["Register action"](tools_menu_item_action.png){width="350"} @@ -132,6 +139,7 @@ Selecting the action from the menu, keyboard/mouse shortcuts, or Find Action won However, it confirms the new entry appears at **Tools \| Pop Dialog Action** and **Help \| Find Action...**. ## Developing the `AnAction` Methods + At this point, the new action `PopupDialogAction` is registered with the IntelliJ Platform and functions in the sense that `update()` and `actionPerformed()` are called in response to user interaction with the IDE Tools menu. However, neither method implements any code to perform useful work. @@ -140,6 +148,7 @@ The `update()` method defaults to always enable the action, which is satisfactor So `actionPerformed()` will be developed first. ### Extending the `actionPerformed()` Method + Adding code to the `PopupDialogAction.actionPerformed()` method makes the action do something useful. The code below gets information from the `anActionEvent` input parameter and constructs a message dialog. A generic icon, and the `dlgMsg` and `dlgTitle` attributes from the invoking menu action are displayed. @@ -167,6 +176,7 @@ See [Determining the Action Context](basic_action_system.md#determining-the-acti ``` ### Extending the `update()` Method + Adding code to `PopupDialogAction.update()` gives finer control of the action's visibility and availability. The action's state and(or) presentation can be dynamically changed depending on the context. @@ -195,11 +205,13 @@ The `update()` method does not check to see if a `Navigatable` object is availab This check is unnecessary because using the `Navigatable` object is opportunistic in `actionPerformed()`. See [Determining the Action Context](basic_action_system.md#determining-the-action-context) for more information about accessing information from the `AnActionEvent` input parameter. -### Other Method Overrides +### Other Methods Overrides + A constructor is overridden in `PopupDialogAction`, but this is an artifact of reusing this class for a dynamically created menu action. Otherwise, overriding constructors for `AnAction` is not required. ## Testing the Custom Action + After compiling and running the plugin project and invoking the action, the dialog will pop up: ![Action performed](action_performed.png){width="800"} diff --git a/topics/tutorials/custom_language_support/reference_contributor.md b/topics/tutorials/custom_language_support/reference_contributor.md index 8676aa242..56bd04584 100644 --- a/topics/tutorials/custom_language_support/reference_contributor.md +++ b/topics/tutorials/custom_language_support/reference_contributor.md @@ -90,7 +90,7 @@ public class SimpleElementFactory { ``` ## Update Grammar and Regenerate the Parser -Now make corresponding changes to the `Simple.bnf` grammar file by replacing the `property` definition with the lines below. +Now make corresponding changes to the Simple.bnf grammar file by replacing the `property` definition with the lines below. Don't forget to regenerate the parser after updating the file! Right-click on the Simple.bnf file and select **Generate Parser Code**. diff --git a/topics/tutorials/framework.md b/topics/tutorials/framework.md index 5303a5994..e966cdacd 100644 --- a/topics/tutorials/framework.md +++ b/topics/tutorials/framework.md @@ -14,7 +14,7 @@ public class DemoFramework extends FrameworkTypeEx { ``` ## Registering Framework -The newly created framework class should be registered as an extension point by adding `com.intellij.framework.type` extension in [`plugin.xml`](https://github.com/JetBrains/intellij-sdk-code-samples/blob/main/framework_basics/src/main/resources/META-INF/plugin.xml) configuration file: +The newly created framework class should be registered as an extension point by adding `com.intellij.framework.type` extension in [`plugin.xml`](https://github.com/JetBrains/intellij-sdk-code-samples/blob/main/framework_basics/src/main/resources/META-INF/plugin.xml) configuration file: ```xml @@ -34,6 +34,7 @@ public class DemoFramework extends FrameworkTypeEx { protected DemoFramework() { super(FRAMEWORK_ID); } +} ``` The *Presentable name* and *icon* define the appearance of visual components related to the framework: @@ -60,43 +61,42 @@ To make the framework set up available while executing the steps to create a pro In this example the framework is added to any [`ModuleType`](upsource:///platform/lang-core/src/com/intellij/openapi/module/ModuleType.java) without checking, which is usually not the case. ```java - @NotNull - @Override - public FrameworkSupportInModuleProvider createProvider() { - return new FrameworkSupportInModuleProvider() { - @NotNull - @Override - public FrameworkTypeEx getFrameworkType() { - return DemoFramework.this; - } +@NotNull +@Override +public FrameworkSupportInModuleProvider createProvider() { + return new FrameworkSupportInModuleProvider() { + @NotNull + @Override + public FrameworkTypeEx getFrameworkType() { + return DemoFramework.this; + } - @NotNull - @Override - public FrameworkSupportInModuleConfigurable createConfigurable(@NotNull FrameworkSupportModel model) { - return new FrameworkSupportInModuleConfigurable() { + @NotNull + @Override + public FrameworkSupportInModuleConfigurable createConfigurable(@NotNull FrameworkSupportModel model) { + return new FrameworkSupportInModuleConfigurable() { - @Override - public JComponent createComponent() { - return new JCheckBox("SDK Extra Option"); - } + @Override + public JComponent createComponent() { + return new JCheckBox("SDK Extra Option"); + } - @Override - public void addSupport(@NotNull Module module, - @NotNull ModifiableRootModel model, - @NotNull ModifiableModelsProvider provider) { - // This is the place to set up a library, generate a specific file, etc - // and actually add framework support to a module. - } - }; - } - - @Override - public boolean isEnabledForModuleType(@NotNull ModuleType type) { - return true; - } - }; - } + @Override + public void addSupport(@NotNull Module module, + @NotNull ModifiableRootModel model, + @NotNull ModifiableModelsProvider provider) { + // This is the place to set up a library, generate a specific file, etc + // and actually add framework support to a module. + } + }; + } + @Override + public boolean isEnabledForModuleType(@NotNull ModuleType type) { + return true; + } + }; +} ``` ## Compile and Run the Plugin