From 7bead165bc2b6febcecf3ba71e1d4303d080dd66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yann=20C=C3=A9bron?= Date: Wed, 22 Apr 2020 15:02:27 +0200 Subject: [PATCH] fix title capitalization --- README.md | 2 +- _SUMMARY.md | 4 +- .../general_threading_rules.md | 4 +- .../architectural_overview/navigating_psi.md | 4 +- basics/getting_started/build_number_ranges.md | 8 ++-- basics/getting_started/publishing_plugin.md | 2 +- basics/indexing_and_psi_stubs.md | 2 +- .../file_based_indexes.md | 8 ++-- basics/indexing_and_psi_stubs/stub_indexes.md | 2 +- basics/persisting_sensitive_data.md | 6 +-- basics/platform_contributions.md | 16 +++---- basics/plugin_structure/dynamic_plugins.md | 12 +++--- .../plugin_extension_points.md | 6 +-- basics/plugin_structure/plugin_extensions.md | 4 +- basics/plugin_structure/plugin_listeners.md | 4 +- basics/plugin_structure/plugin_services.md | 2 +- basics/run_configurations.md | 2 +- .../run_configuration_execution.md | 6 +-- .../run_configuration_management.md | 14 +++---- basics/virtual_file_system.md | 4 +- intro/about.md | 2 +- intro/getting_help.md | 6 +-- intro/key_topics.md | 6 +-- intro/sdk_style.md | 4 +- .../api_changes/api_changes_list_2017.md | 4 +- .../api_changes/api_changes_list_2018.md | 2 +- .../api_changes/api_changes_list_2019.md | 14 +++---- .../api_changes/api_changes_list_2020.md | 2 +- .../code_completion.md | 2 +- ...tax_highlighting_and_error_highlighting.md | 4 +- .../external_builder_api.md | 14 +++---- .../external_system_integration.md | 14 +++---- .../spring_api.md | 42 +++++++++---------- .../xml_dom_api.md | 12 +++--- reference_guide/messaging_infrastructure.md | 12 +++--- reference_guide/multiple_carets.md | 12 +++--- reference_guide/performance/performance.md | 21 ++++++---- reference_guide/project_model/facet.md | 2 +- reference_guide/project_model/module.md | 6 +-- reference_guide/project_model/project.md | 2 +- reference_guide/ui_themes/themes_customize.md | 2 +- reference_guide/ui_themes/themes_metadata.md | 4 +- reference_guide/work_with_icons_and_images.md | 6 +-- tutorials/build_system/gradle_guide.md | 2 +- tutorials/build_system/prerequisites.md | 2 +- .../code_style_settings.md | 2 +- .../custom_language_support/quick_fix.md | 2 +- ...tax_highlighter_and_color_settings_page.md | 2 +- tutorials/framework.md | 8 ++-- tutorials/kotlin.md | 4 +- tutorials/project_wizard/adding_new_steps.md | 2 +- tutorials/project_wizard/module_types.md | 2 +- tutorials/run_configurations.md | 4 +- tutorials/tree_structure_view.md | 4 +- user_interface_components/kotlin_ui_dsl.md | 4 +- 55 files changed, 174 insertions(+), 171 deletions(-) diff --git a/README.md b/README.md index 7a8faf311..623115c65 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Please report any content inconsistencies, outdated materials, cosmetic issues a ## Working With the Site Locally To check out and run a local copy of the site follow the steps described below. -### Pre-requirements +### Pre-Requirements * Make sure you have a [git client](https://git-scm.com/downloads) diff --git a/_SUMMARY.md b/_SUMMARY.md index 29db1e127..e5e5f951e 100644 --- a/_SUMMARY.md +++ b/_SUMMARY.md @@ -124,7 +124,7 @@ * [External System Integration](reference_guide/frameworks_and_external_apis/external_system_integration.md) ## Part IV - PSI -* [What is the PSI?](basics/architectural_overview/psi.md) +* [What Is the PSI?](basics/architectural_overview/psi.md) * [PSI Files](basics/architectural_overview/psi_files.md) * [File View Providers](basics/architectural_overview/file_view_providers.md) * [PSI Elements](basics/architectural_overview/psi_elements.md) @@ -133,7 +133,7 @@ * [Modifying the PSI](basics/architectural_overview/modifying_psi.md) * [PSI Cookbook](basics/psi_cookbook.md) * [Indexing and PSI Stubs](basics/indexing_and_psi_stubs.md) - * [File-based indexes](basics/indexing_and_psi_stubs/file_based_indexes.md) + * [File-Based Indexes](basics/indexing_and_psi_stubs/file_based_indexes.md) * [Stub Indexes](basics/indexing_and_psi_stubs/stub_indexes.md) * Element Patterns * Unified AST diff --git a/basics/architectural_overview/general_threading_rules.md b/basics/architectural_overview/general_threading_rules.md index 43655618d..9d23ea621 100644 --- a/basics/architectural_overview/general_threading_rules.md +++ b/basics/architectural_overview/general_threading_rules.md @@ -3,7 +3,7 @@ title: General Threading Rules --- -## Read/write lock +## Read/Write Lock In general, code-related data structures in the *IntelliJ Platform* are covered by a single reader/writer lock. This applies to PSI, VFS and project root model. @@ -49,7 +49,7 @@ The `checkCanceled()` should be called often enough to guarantee smooth cancella have a lot of `checkCanceled()` calls inside. But if your process does lengthy non-PSI activity, you might need to insert explicit `checkCanceled()` calls so that it happens frequently, e.g. on each _Nth_ loop iteration. -## Read action cancellability +## Read Action Cancellability Background threads shouldn't take plain read actions for a long time. The reason is that if the UI thread needs a write action (e.g. the user types something), it must be acquired as soon as possible, otherwise the UI will freeze until all background threads have released their read actions. diff --git a/basics/architectural_overview/navigating_psi.md b/basics/architectural_overview/navigating_psi.md index c1e29e3cb..9b31d5018 100644 --- a/basics/architectural_overview/navigating_psi.md +++ b/basics/architectural_overview/navigating_psi.md @@ -12,7 +12,7 @@ the element in which it has been declared). Finally, *references* allow you to n [separate topic](psi_references.md). -## Top-down navigation +## Top-Down Navigation The most common way to perform top-down navigation is to use a *visitor*. To use a visitor, you create a class (usually an anonymous inner class) that extends the base visitor class, override the methods that handle the elements @@ -41,7 +41,7 @@ all methods in a Java class, you can do that using a visitor, but a much easier general-purpose, language-independent functions for PSI tree navigation, some of which (for example, `findChildrenOfType()`) perform top-down navigation. -## Bottom-up navigation +## Bottom-Up Navigation The starting point for bottom-up navigation is either a specific element in the PSI tree (for example, the result of resolving a reference), or an offset. If you have an offset, you can find the corresponding PSI element by calling diff --git a/basics/getting_started/build_number_ranges.md b/basics/getting_started/build_number_ranges.md index e6901eb61..9d5d941f2 100644 --- a/basics/getting_started/build_number_ranges.md +++ b/basics/getting_started/build_number_ranges.md @@ -37,7 +37,7 @@ Multi-part build numbers can also be used in the `since-build` and `until-build` > **NOTE** Specific build numbers and their corresponding release version are available via _Previous Releases_ on the corresponding product's download page, e.g. [Previous IntelliJ IDEA Releases](https://www.jetbrains.com/idea/download/previous.html). -### IntelliJ Platform based products of recent IDE versions +### IntelliJ Platform Based Products of Recent IDE Versions > **TIP** Which versions should your plugin support? We've collected some insights based on download statistics in [Statistics: Product Versions in Use](https://plugins.jetbrains.com/docs/marketplace/product-versions-in-use-statistics.html). @@ -58,7 +58,7 @@ Multi-part build numbers can also be used in the `since-build` and `until-build` Note that there is no `170`. In the `YYYY.R` versioning scheme, the `R` part starts at 1. -### IntelliJ Platform based products of pre-2016.2 IDE versions +### IntelliJ Platform Based Products of Pre-2016.2 IDE Versions | Branch number | Product version | |---------------|-----------------| @@ -85,7 +85,7 @@ Note that there is no `170`. In the `YYYY.R` versioning scheme, the `R` part sta ## History -### Build numbers for IntelliJ IDEA versions +### Build Numbers for IntelliJ IDEA Versions | IntelliJ IDEA version | Build number | |-----------------------|---------------| @@ -110,7 +110,7 @@ Note that there is no `170`. In the `YYYY.R` versioning scheme, the `R` part sta | 9.0.1 | 93.94 | | 9.0 | 93.13 | -### Build numbers for IntelliJ IDEA pre-9.0 +### Build Numbers for IntelliJ IDEA Pre-9.0 Before IntelliJ IDEA 9.0, linear build numbers were used, with the following ranges: diff --git a/basics/getting_started/publishing_plugin.md b/basics/getting_started/publishing_plugin.md index 6c45674c6..ea92c8e7b 100644 --- a/basics/getting_started/publishing_plugin.md +++ b/basics/getting_started/publishing_plugin.md @@ -1,5 +1,5 @@ --- -title: Publishing a plugin +title: Publishing a Plugin --- diff --git a/basics/indexing_and_psi_stubs.md b/basics/indexing_and_psi_stubs.md index 6b18a728b..7659c2d86 100644 --- a/basics/indexing_and_psi_stubs.md +++ b/basics/indexing_and_psi_stubs.md @@ -19,7 +19,7 @@ Querying a file-based index gets you the set of files matching a certain conditi >> **TIP** [Indices Viewer](https://plugins.jetbrains.com/plugin/13029-indices-viewer/) is a plugin that helps inspecting indices' contents and properties. Please see also [Improving indexing performance](/reference_guide/performance/performance.md#improving-indexing-performance). -## Dumb mode +## Dumb Mode Indexing is a potentially long process. It's performed in background, and during this time, IDE's features are restricted to the ones that don't require index: basic text editing, version control etc. This restriction is managed by [`DumbService`](upsource:///platform/core-api/src/com/intellij/openapi/project/DumbService.java). diff --git a/basics/indexing_and_psi_stubs/file_based_indexes.md b/basics/indexing_and_psi_stubs/file_based_indexes.md index 039a65f93..fb341e254 100644 --- a/basics/indexing_and_psi_stubs/file_based_indexes.md +++ b/basics/indexing_and_psi_stubs/file_based_indexes.md @@ -1,5 +1,5 @@ --- -title: File-based Indexes +title: File-Based Indexes --- @@ -19,7 +19,7 @@ When the index implementation indexes a file, it receives the content of a file When you access the index, you specify the key that you're interested in and get back the list of files in which the key occurs and the value associated with each file. -## Implementing a file-based index +## Implementing a File-Based Index A fairly simple file-based index implementation is the [UI Designer bound forms index](upsource:///plugins/ui-designer/src/com/intellij/uiDesigner/binding/FormClassIndex.java). Refer to it as an example to understand this topic better. @@ -41,7 +41,7 @@ If you don't need to associate any value with the files (i.e. your value type is > **Note** Please see `com.intellij.util.indexing.DebugAssertions` on how to enable additional debugging assertions during development to assert correct index implementation. -## Accessing a file-based index +## 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. @@ -57,7 +57,7 @@ The following primary operations are supported: > **WARNING** Nested index access is forbidden as it might lead to a deadlock. Collect all necessary data from index A first, then process results while accessing index B. -## Standard indexes +## Standard Indexes The *IntelliJ Platform* contains a number of standard file-based indexes. The most useful indexes for plugin developers are: diff --git a/basics/indexing_and_psi_stubs/stub_indexes.md b/basics/indexing_and_psi_stubs/stub_indexes.md index f89f15e2f..810b99b24 100644 --- a/basics/indexing_and_psi_stubs/stub_indexes.md +++ b/basics/indexing_and_psi_stubs/stub_indexes.md @@ -38,7 +38,7 @@ By default, if a PSI element extends `StubBasedPsiElement`, all elements of that It's essential to make sure that all information stored in the stub tree depends only on the contents of the file for which stubs are being built, and does not depend on any external files. Otherwise the stub tree will not be rebuilt when an external dependency changes, and you will have stale and incorrect data in the stub tree. -## Stub indexes +## Stub Indexes When building the stub tree, you can at the same time put some data about the stub elements into a number of indexes, which then can be used to find the PSI elements by the corresponding key. Unlike file-based indexes, stub indexes do not support storing custom data as values; the value is always a PSI element. Keys in stub indexes are normally strings (such as class names); other data types are also supported if desired. diff --git a/basics/persisting_sensitive_data.md b/basics/persisting_sensitive_data.md index bc49cb58e..a5434b4f2 100644 --- a/basics/persisting_sensitive_data.md +++ b/basics/persisting_sensitive_data.md @@ -5,10 +5,10 @@ title: Persisting Sensitive Data The Credentials Store API allows you to securely store sensitive user data, like passwords, server URLs, etc. -## How to use +## How to Use Use [`PasswordSafe`](upsource:///platform/platform-api/src/com/intellij/ide/passwordSafe/PasswordSafe.kt) to work with credentials. -### Retrieve stored credentials +### Retrieve Stored Credentials ```java String key = null; // e.g. serverURL, accountID @@ -27,7 +27,7 @@ Use [`PasswordSafe`](upsource:///platform/platform-api/src/com/intellij/ide/pass } ``` -### Store credentials +### Store Credentials ```java CredentialAttributes credentialAttributes = createCredentialAttributes(serverId); // see previous sample diff --git a/basics/platform_contributions.md b/basics/platform_contributions.md index c3487eda0..8bcba8c32 100644 --- a/basics/platform_contributions.md +++ b/basics/platform_contributions.md @@ -7,7 +7,7 @@ Please make sure to read the [Code of Conduct](../CODE_OF_CONDUCT.md). #### Participate in the Community -##### Participate in newsgroups and forums +##### Participate in Newsgroups and Forums There are several community [forums and newsgroups](https://intellij-support.jetbrains.com/hc/en-us/community/topics) you can join to discuss the IntelliJ Platform. The forums are an excellent source for users and contributors interested in having technical discussions, answering questions, or resolving potential issues for newcomers. ##### Link to jetbrains.org @@ -18,28 +18,28 @@ Help promote the platform and IDE by using your blog, Twitter, Facebook, or subm #### Help Others Learn -##### Write documents +##### Write Documents We're always looking for new articles about IntelliJ IDEA features as well as documentation for the IntelliJ Platform. You can write tutorials, how-tos, sample applications, or just share your experience with the IntelliJ Platform. You can publish your documentation on an website or blog, or submit a [pull request](/CONTRIBUTING.md) to the SDK Docs. -##### Produce screencasts +##### Produce Screencasts Screencasts have recently become very popular as a way to show other developers how to use the tool effectively. You can record a screencast about a particular feature or use case you discovered and would like to share it with the community. #### Contribute Code -##### File a bug report +##### File a Bug Report Bug reports take little time to file and are very helpful to developers. This is one of the easiest contributions you can make. When you discover a problem with the IDE or the platform, please report it. Make sure you provide information about your environment (OS, JDK version), steps to reproduce the issue, as well as a written description of the problem. You can file a bug in our [YouTrack issue tracker](https://youtrack.jetbrains.com/issues/IDEA). Before submitting an issue, please search for already submitted ones describing the same problem - and if you find one, feel free to vote for it. -##### Help us triage existing bug reports +##### Help Triage Existing Bug Reports Over the years, users have submitted thousands of issues to the IntelliJ issue tracker. Many of the unresolved issues are no longer applicable to the latest version of IntelliJ IDEA, are duplicates, or require additional information to be resolved. Leaving comments notifying about the status of such issues helps the team keep the issue tracker clean and useful for everyone. -##### Write a plugin +##### Write a Plugin One of the best ways to contribute a larger piece of code, adding extra functionality to IntelliJ IDEA, is by writing a plug-in. You can submit a plug-in to the [IntelliJ IDEA plug-in repository](https://plugins.jetbrains.com/), making it available for all IntelliJ IDEA users. When writing a plug-in, you have control over the code and don't need to sign the contribution agreement. -##### Submit a patch +##### Submit a Patch If you would like to improve the code in the IntelliJ Platform or the core functionality of IntelliJ IDEA, you can submit a patch in [IntelliJ's YouTrack bug database](https://youtrack.jetbrains.com/issues/IDEA) . You can either file a new issue with the patch attached, or attach a patch to an issue submitted by another user. When writing a patch, please make sure to follow the [IntelliJ Coding Guidelines](intellij_coding_guidelines.md). Alternatively, you can fork [the IntelliJ IDEA repository on GitHub](https://github.com/JetBrains/intellij-community), make the changes in your fork and send us a pull request. A developer will review your patch and, if it meets the [quality criteria](intellij_coding_guidelines.md) and fits well with the rest of the code, you'll be notified about the acceptance of the patch. You will also need to sign the [contribution agreement](https://www.jetbrains.org/display/IJOS/Contributor+Agreement) in order to complete your contribution. -##### Become a committer and commit code directly +##### Become a Committer Developers with a long history of submitting high-quality patches can gain direct commit rights. diff --git a/basics/plugin_structure/dynamic_plugins.md b/basics/plugin_structure/dynamic_plugins.md index 033a0fafc..22e12cae1 100644 --- a/basics/plugin_structure/dynamic_plugins.md +++ b/basics/plugin_structure/dynamic_plugins.md @@ -11,22 +11,22 @@ inspection on all plugin descriptor files (required `plugin.xml` as well as any For plugins hosted on the [JetBrains plugin repository](/plugin_repository/index.md) the built-in [Plugin Verifier](https://blog.jetbrains.com/platform/2018/07/plugins-repository-now-integrates-with-the-plugin-verification-tool/) will run these checks automatically. See [Plugin Verifier](/reference_guide/api_changes_list.md#plugin-verifier) for more information on how to run it locally. -### No use of Components +### No Use of Components No Components must be used; existing ones [must be migrated](plugin_components.md) to services, extensions or listeners. -### Action Group requires ID +### Action Group Requires ID All ``s must declare a unique `id`. -### Use only dynamic Extensions +### Use Only Dynamic Extensions All extensions, whether defined in the platform itself or coming from other plugins, must be marked as dynamic (see next paragraph). -### Mark Extension Points as dynamic +### Mark Extension Points as Dynamic All extension points provided by the plugin must adhere to specific usage rules and then [be declared](plugin_extension_points.md#dynamic-extension-points) ready for dynamic use explicitly. -### Configurables depending on Extension Points +### Configurables Depending on Extension Points Any `Configurable` which depends on dynamic extension points must implement `Configurable.WithEpDependencies`. -### No use of service overrides +### No Use of Service Overrides Application, project and module services declared with `overrides="true"` are not allowed. ## Plugin Load/Unload Events diff --git a/basics/plugin_structure/plugin_extension_points.md b/basics/plugin_structure/plugin_extension_points.md index f40810c61..496d172b7 100644 --- a/basics/plugin_structure/plugin_extension_points.md +++ b/basics/plugin_structure/plugin_extension_points.md @@ -14,7 +14,7 @@ There are two types of extension points: * _Bean_ extension points allow other plugins to extend your plugins with _data_. You specify the fully qualified name of an extension class, and other plugins will provide data which will be turned into instances of that class. -## How to declare extension points +## How to Declare Extension Points You can declare extensions and extension points in the plugin configuration file `plugin.xml`, within the `` and `` sections, respectively. @@ -89,7 +89,7 @@ _anotherPlugin/META-INF/plugin.xml_ ``` -## Using extension points +## Using Extension Points To refer to all registered extension instances at runtime, declare an [`ExtensionPointName`](upsource:///platform/extensions/src/com/intellij/openapi/extensions/ExtensionPointName.java) passing in the fully-qualified name matching its [declaration in `plugin.xml`](#how-to-declare-extension-points). _myPlugin/src/com/myplugin/MyExtensionUsingService.java_ @@ -111,7 +111,7 @@ public class MyExtensionUsingService { A gutter icon for the `ExtensionPointName` declaration allows navigating to the corresponding `` declaration in `plugin.xml`. -## Dynamic extension points +## Dynamic Extension Points To support [Dynamic Plugins](dynamic_plugins.md) (2020.1 and later), an extension point must adhere to specific usage rules: - extensions are enumerated on every use and extensions instances are not stored anywhere diff --git a/basics/plugin_structure/plugin_extensions.md b/basics/plugin_structure/plugin_extensions.md index 0b6471881..eba49d89e 100644 --- a/basics/plugin_structure/plugin_extensions.md +++ b/basics/plugin_structure/plugin_extensions.md @@ -52,7 +52,7 @@ To clarify this procedure, consider the following sample section of the `plugin. ``` -### Extension default properties +### Extension Default Properties The following properties are available always: - `id` - unique ID @@ -60,7 +60,7 @@ The following properties are available always: - `os` - allows to restrict extension to given OS, e.g., `os="windows"` registers the extension on Windows only -### Extension properties code insight +### Extension Properties Code Insight Several tooling features are available to help configuring bean class extension points in `plugin.xml`. Properties annotated with [`@RequiredElement`](upsource:///platform/extensions/src/com/intellij/openapi/extensions/RequiredElement.java) are inserted automatically and validated (2019.3 and later). diff --git a/basics/plugin_structure/plugin_listeners.md b/basics/plugin_structure/plugin_listeners.md index e7f8b7864..5053f0005 100644 --- a/basics/plugin_structure/plugin_listeners.md +++ b/basics/plugin_structure/plugin_listeners.md @@ -61,7 +61,7 @@ public class MyVfsListener implements BulkFileListener { } ``` -## Defining Project-level Listeners +## Defining Project-Level Listeners Project-level listeners are registered in the same way, except that the top-level tag is ``. They can be used to listen to project-level events, for example, tool window operations: @@ -90,7 +90,7 @@ public class MyToolwindowListener implements ToolWindowManagerListener { } ``` -## Additional attributes +## Additional Attributes Registration of listeners can be restricted using the following attributes: diff --git a/basics/plugin_structure/plugin_services.md b/basics/plugin_structure/plugin_services.md index ec68f930a..b6b748c75 100644 --- a/basics/plugin_structure/plugin_services.md +++ b/basics/plugin_structure/plugin_services.md @@ -67,7 +67,7 @@ Project/Module level service constructor can take `Project`/`Module` argument. To improve startup performance, avoid any heavy initializations in the constructor. -## Retrieving a service +## Retrieving a Service Getting service doesn't need read action and can be performed from any thread. If service is requested from several threads, it will be initialized in the first thread, and other threads will be blocked until service is fully initialized. diff --git a/basics/run_configurations.md b/basics/run_configurations.md index 23261aeef..14e5b3209 100644 --- a/basics/run_configurations.md +++ b/basics/run_configurations.md @@ -5,7 +5,7 @@ title: Run Configurations *Run Configurations* allow users to run a certain type of external processes from within the IDE, e.g. a script, an application, a server, etc. You can provide UI for the user to specify execution options, as well as an option to create a run configuration based on a specific location in the source code. -# Architectural overview +# Architectural Overview Classes used to manipulate run configurations can be split into the following groups: diff --git a/basics/run_configurations/run_configuration_execution.md b/basics/run_configurations/run_configuration_execution.md index c24c7af54..249a887d6 100644 --- a/basics/run_configurations/run_configuration_execution.md +++ b/basics/run_configurations/run_configuration_execution.md @@ -24,7 +24,7 @@ The three default executors provided by the *IntelliJ Platform* by default are _ As a plugin developer, you normally don't need to implement the `Executor` interface. However, it can be useful, for example, if you're implementing a profiler integration and want to provide the possibility to execute any configuration with profiling. -## Running a process +## Running a Process The `RunProfileState` interface comes up in every run configuration implementation as the return value `RunProfile.getState()`. It describes a process which is ready to be started and holds the information like the command line, current working directory, and environment variables for the process to be started. (The existence of `RunProfileState` as a separate step in the execution flow allows run configuration extensions and other components to patch the configuration and to modify the parameters before it gets executed.) @@ -34,7 +34,7 @@ Alternatively, if the process you need to run is a JVM-based one, you can use th To monitor the execution of a process and capture its output, the [`OSProcessHandler`](upsource:///platform/platform-util-io/src/com/intellij/execution/process/OSProcessHandler.java) class is normally used. Once you've created an instance of `OSProcessHandler` from either a command line or a Process object, you need to call the `startNotify()` method to start capturing its output. You may also want to attach a [`ProcessTerminatedListener`](upsource:///platform/platform-api/src/com/intellij/execution/process/ProcessTerminatedListener.java) to the `OSProcessHandler`, so that the exit status of the process will be displayed in the console. -## Displaying the process output +## Displaying Process Output If you're using `CommandLineState`, a console view will be automatically created and attached to the output of the process. Alternatively, you can arrange this yourself: @@ -47,6 +47,6 @@ Console [filters](upsource:///platform/lang-api/src/com/intellij/execution/filte Two common filter implementations you may want to reuse are [`RegexpFilter`](upsource:///platform/lang-api/src/com/intellij/execution/filters/RegexpFilter.java) and [`UrlFilter`](upsource:///platform/lang-api/src/com/intellij/execution/filters/UrlFilter.java). -## Starting a run configuration from code +## Starting a Run Configuration from Code If you have an existing run configuration that you need to execute, the easiest way to do so is to use [`ProgramRunnerUtil.executeConfiguration()`](upsource:///platform/execution-impl/src/com/intellij/execution/ProgramRunnerUtil.java). The method takes a [`Project`](upsource:///platform/core-api/src/com/intellij/openapi/project/Project.java), a [`RunnerAndConfigurationSettings`](upsource:///platform/lang-api/src/com/intellij/execution/RunnerAndConfigurationSettings.java), as well as an [`Executor`](upsource:///platform/lang-api/src/com/intellij/execution/Executor.java). To get the `RunnerAndConfigurationSettings` for an existing configuration, you can use, for example, `RunManager.getConfigurationSettings(ConfigurationType)`. As the last parameter, you normally pass either `DefaultRunExecutor.getRunExecutorInstance()` or `DefaultDebugExecutor.getDebugExecutorInstance()`. diff --git a/basics/run_configurations/run_configuration_management.md b/basics/run_configurations/run_configuration_management.md index eb132e08f..bdb47e04f 100644 --- a/basics/run_configurations/run_configuration_management.md +++ b/basics/run_configurations/run_configuration_management.md @@ -8,7 +8,7 @@ This document describes main classes to work with run configurations and common * Dummy table of contents {:toc} -## Configuration type +## Configuration Type The starting point for implementing any run configuration type is the [`ConfigurationType`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java) interface. The list of available configuration types is shown when a user opens the _'Edit run configurations'_ dialog and executes _'Add'_ action: @@ -22,7 +22,7 @@ Every type there is represented as an instance of [`ConfigurationType`](upsource The easiest way to implement this interface is to use the [`ConfigurationTypeBase`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/runConfigurationType.kt) base class. In order to use it, you need to inherit from it and to provide the configuration type parameters (ID, name, description and icon) as constructor parameters. In addition to that, you need to call the [`addFactory()`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/runConfigurationType.kt) method to add a configuration factory. -## Configuration factory +## Configuration Factory All run configurations are created by the [`ConfigurationFactory`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java) registered for a particular `ConfigurationType`. It's possible that one `ConfigurationType` [has more than one](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java) `ConfigurationFactory`: @@ -34,7 +34,7 @@ All real run configurations (loaded from the workspace or created by the user) a You can customize additional aspects of your configuration factory by overriding the [`getIcon`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java), [`getAddIcon`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java), [`getName`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java) and the default settings methods. These additional overrides are optional. -## Run configuration +## Run Configuration The run configuration itself is represented by the [`RunConfiguration`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/RunConfiguration.java) interface. A _'run configuration'_ here is some named profile which can be executed, e.g. application started via `main()` class, test, remote debug to particular machine/port etc. @@ -48,7 +48,7 @@ When implementing a run configuration, you may want to use one of the common bas * [`LocatableConfigurationBase`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/LocatableConfigurationBase.java) is a common base class that should be used for configurations that can be created from context by a `RunConfigurationProducer`. It supports automatically generating a name for a configuration from its settings and keeping track of whether the name was changed by the user. * [`ModuleBasedConfiguration`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ModuleBasedConfiguration.java) is a base class for a configuration that is associated with a specific module (for example, Java run configurations use the selected module to determine the run classpath). -## Settings editor +## Settings Editor That common run configuration settings might be modified via: @@ -69,7 +69,7 @@ Dealing with instances of this class becomes necessary when you need to create r * `RunManager.createConfiguration()` creates an instance of `RunnerAndConfigurationSettings`. * `RunManager.addConfiguration()` makes it persistent by adding it to either the list of shared configurations stored in a project, or to the list of local configurations stored in the workspace file. -## Refactoring support +## Refactoring Support Most run configurations contain references to classes, files or directories in their settings, and these settings usually need to be updated when the corresponding element is renamed or moved. @@ -77,7 +77,7 @@ In order to support that, your run configuration needs to implement the [`Refact In your implementation of `getRefactoringElementListener()`, you need to check whether the element being refactored is the one that your run configuration refers to, and if it is, you return a [`RefactoringElementListener`](upsource:///platform/analysis-api/src/com/intellij/refactoring/listeners/RefactoringElementListener.java) that updates your configuration according to the new name and location of the element. -## Creating configurations from context +## Creating Configurations from Context Many plugins support automatic creation of run configurations from context, so that the user can click, for example, on an application or test class and automatically run it using the correct run configuration type. In order to support that, you need to provide an implementation of the [`RunConfigurationProducer`](upsource:///platform/lang-api/src/com/intellij/execution/actions/RunConfigurationProducer.java) interface and to register it as `` in your `plugin.xml`. (Note that this API has been redesigned in IntelliJ IDEA 13; the old [`RuntimeConfigurationProducer`](upsource:///platform/lang-api/src/com/intellij/execution/junit/RuntimeConfigurationProducer.java) is a much more confusing version of the same API). @@ -90,6 +90,6 @@ The two main methods that you need to implement are: Note that, in order to support automatic naming of configurations created from context, your configuration should use [`LocatableConfigurationBase`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/LocatableConfigurationBase.java) as the base class. -## Running from the gutter +## Running from the Gutter Take a look at [`RunLineMarkerContributor`](upsource:///platform/execution-impl/src/com/intellij/execution/lineMarker/RunLineMarkerContributor.java) and its implementations. diff --git a/basics/virtual_file_system.md b/basics/virtual_file_system.md index 2677fa393..14534a568 100644 --- a/basics/virtual_file_system.md +++ b/basics/virtual_file_system.md @@ -37,7 +37,7 @@ The VFS itself does not honor ignored files listed in **Settings \| File Types \ During the lifetime of a running instance of an IntelliJ Platform IDE, multiple `VirtualFile` instances may correspond to the same disk file. They are equal, have the same `hashCode` and share the user data. -## Synchronous and asynchronous refreshes +## Synchronous and Asynchronous Refreshes From the point of view of the caller, refresh operations can be either synchronous or asynchronous. In fact, the refresh operations are executed according to their own threading policy, and the synchronous flag simply means that the calling thread will be blocked until the refresh operation (which will most likely run on a different thread) is completed. @@ -52,7 +52,7 @@ In nearly all cases, using asynchronous refreshes is strongly preferred. If ther Synchronous refreshes can cause deadlocks in some cases, depending on which locks are held by the thread invoking the refresh operation. -## Virtual file system events +## Virtual File System Events All changes happening in the virtual file system, either as a result of refresh operations or caused by user's actions, are reported as _virtual file system events_. VFS events are always fired in the event dispatch thread, and in a write action. diff --git a/intro/about.md b/intro/about.md index f78afe222..8e727d317 100644 --- a/intro/about.md +++ b/intro/about.md @@ -1,5 +1,5 @@ --- -title: About this Guide +title: About This Guide --- diff --git a/intro/getting_help.md b/intro/getting_help.md index 0dae38cce..1318d149a 100644 --- a/intro/getting_help.md +++ b/intro/getting_help.md @@ -3,7 +3,7 @@ title: Getting Help --- -## Problems with the guide +## Problems with the Guide If you’re having problems with the guide itself, such as missing, incorrect or confusing content, please [raise an issue on YouTrack](https://youtrack.jetbrains.com/newIssue?project=IJSDK&clearDraft=true&c=). If the problem is easily solved, you can also submit a [Pull Request on GitHub](https://github.com/JetBrains/intellij-sdk-docs). @@ -11,7 +11,7 @@ If you just want to share feedback on the guide, again, [raise an issue](https:/ > **Note** Please don't use the **IJSDK** YouTrack project for plugin or product support requests - it's intended for the SDK and the documentation, and you'll get a better response using one of the methods below. -## Problems with code - support issues +## Problems with Code - Support Issues For problems related to code, rather than the content of the guide, you have several options: @@ -20,6 +20,6 @@ For problems related to code, rather than the content of the guide, you have sev Of course, all issues will be used to try and improve this guide. -## Problems with products +## Problems with Products If you have a problem with an IntelliJ Platform-based product, such as IntelliJ IDEA, WebStorm, Rider, etc., please raise an issue on [YouTrack](https://youtrack.jetbrains.com), assigning it to the correct project for the product. diff --git a/intro/key_topics.md b/intro/key_topics.md index f2e30677d..d1305d4b0 100644 --- a/intro/key_topics.md +++ b/intro/key_topics.md @@ -5,7 +5,7 @@ title: Key Topics The _IntelliJ Platform_ is very large, and very capable, and its size and scope can initially be very daunting. This page is intended to list the key topics that a plugin author would be interested in, and provide quick links to the most common extension points. -## Essential concepts +## Essential Concepts - [Getting Started](/basics/getting_started.md) with plugins. - [Testing plugins](/basics/testing_plugins/testing_plugins.md). @@ -13,11 +13,11 @@ The _IntelliJ Platform_ is very large, and very capable, and its size and scope - [Extension points](/basics/plugin_structure/plugin_extensions.md) - how to register components with extension points, and how to find out what extension points are available. - [Virtual files](/basics/architectural_overview/virtual_file.md) - all file access should go through the Virtual File System which abstracts and caches the file system. This means you can work with files that are on the local file system, in a zip file or are old versions from version control. -## Code model +## Code Model The _IntelliJ Platform_'s code model is called the PSI - the [Program Structure Interface](/basics/architectural_overview/psi.md). The PSI parses code, builds indexes and creates a semantic model. -## Common extension points +## Common Extension Points The _IntelliJ Platform_ is extremely extensible, and most features and services can be extended. Some of the common extension points are: diff --git a/intro/sdk_style.md b/intro/sdk_style.md index 41e0ebef3..c010c2cf8 100644 --- a/intro/sdk_style.md +++ b/intro/sdk_style.md @@ -95,7 +95,7 @@ E.g. the following list item will be replaced by links to all of the header item Further Kramdown features are described on the [converter page](https://kramdown.gettalong.org/converter/html.html), and attribute lists are described on the [syntax page](https://kramdown.gettalong.org/syntax.html). Note that source code formatting is configured to use [GitHub Flavoured Markdown](https://help.github.com/articles/github-flavored-markdown/) and "code fences", see below. -### Liquid tags and filters +### Liquid Tags and Filters Jekyll uses the [Liquid](https://shopify.github.io/liquid/) templating language to process files. This process means standard Liquid tags and filters are available. There should be little need to use them, however, as the Markdown format is already quite rich. @@ -218,7 +218,7 @@ General links have one of the following formats: * `[Link to the section on another page](Page2.md#another-section)` links to a heading on another page. -### Notes and callouts +### Notes and Callouts Notes and callouts can be specified using the blockquote syntax. The converter looks at the first following word to see if it is bold. If so, it applies a callout style. diff --git a/reference_guide/api_changes/api_changes_list_2017.md b/reference_guide/api_changes/api_changes_list_2017.md index 7a8ca6bef..f75b5cf12 100644 --- a/reference_guide/api_changes/api_changes_list_2017.md +++ b/reference_guide/api_changes/api_changes_list_2017.md @@ -36,7 +36,7 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h `org.jetbrains.kotlin.idea.configuration.KotlinProjectConfigurator.addLibraryDependency` abstract method added : You need to implement this method and add the logic for updating the configuration in your build system. -## Changes in DataGrip and Database Tools plugin 2017.3 +## Changes in DataGrip and Database Tools Plugin 2017.3 `com.intellij.database.dataSource.DataSourceManager` class removed : Use `com.intellij.database.psi.DbPsiFacade` instead. @@ -53,7 +53,7 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h `com.intellij.database.view.DatabaseView.getTreeBuilder` method removed : Use `LangDataKeys.PSI_ELEMENT_ARRAY.get(event)` to get Database view selection. -## Changes in PhpStorm and PHP plugin 2017.3 +## Changes in PhpStorm and PHP Plugin 2017.3 `com.jetbrains.php.lang.psi.elements.Function.getReturnType()` method return type changed from `PsiElement` to `PhpReturnType` : Before method had been returning a `com.jetbrains.php.lang.psi.elements.ClassReference`. Now method returns `com.jetbrains.php.lang.psi.elements.PhpReturnType`. Method `ReturnType.getClassReference()` can be used if you need just a `ClassReference`. If you need to get the `PhpType`, use `com.jetbrains.php.lang.psi.elements.Function.getReturnType.getType()` method instead. \ No newline at end of file diff --git a/reference_guide/api_changes/api_changes_list_2018.md b/reference_guide/api_changes/api_changes_list_2018.md index 23432f0ff..f45ac006a 100644 --- a/reference_guide/api_changes/api_changes_list_2018.md +++ b/reference_guide/api_changes/api_changes_list_2018.md @@ -95,7 +95,7 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h `com.intellij.ide.structureView.newStructureView.StructureViewComponent.getTreeBuilder` method removed : Use `queueUpdate` and `getTree` instead. -## Changes in PhpStorm and PHP plugin 2018.1 +## Changes in PhpStorm and PHP Plugin 2018.1 `com.jetbrains.php.lang.documentation.phpdoc.parser.PhpDocElementTypes.DOC_COMMENT` field type changed from `com.intellij.psi.tree.ILazyParseableElementType` to `com.jetbrains.php.lang.documentation.phpdoc.psi.stubs.PhpDocCommentElementType` : In most of the cases, it's enough to recompile the code. It may also be needed to check that the code doesn't rely on the field's type. diff --git a/reference_guide/api_changes/api_changes_list_2019.md b/reference_guide/api_changes/api_changes_list_2019.md index 87447053b..5178d2701 100644 --- a/reference_guide/api_changes/api_changes_list_2019.md +++ b/reference_guide/api_changes/api_changes_list_2019.md @@ -133,17 +133,17 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h `com.intellij.testFramework.fixtures.DefaultLightProjectDescriptor.getModuleType()` method removed : Use `com.intellij.testFramework.fixtures.DefaultLightProjectDescriptor.getModuleTypeId()` instead (see `com.intellij.openapi.module.ModuleTypeId`). -## Changes in Java plugin 2019.3 +## Changes in Java Plugin 2019.3 `com.intellij.codeInspection.magicConstant.MagicCompletionContributor.getAllowedValues(PsiElement)` method return type changed from `com.intellij.codeInspection.magicConstant.MagicConstantInspection.AllowedValues` to `com.intellij.codeInspection.magicConstant.MagicConstantUtils.AllowedValues` : Use new type instead. -## Changes in Groovy plugin 2019.3 +## Changes in Groovy Plugin 2019.3 `org.jetbrains.plugins.groovy.extensions.GroovyScriptTypeDetector(GroovyScriptType, String[])` constructor removed : Use constructor `GroovyScriptTypeDetector(GroovyScriptType)` instead, and `com.intellij.fileType` to register additional extensions. -## Changes in Cucumber plugin 2019.3 +## Changes in Cucumber Plugin 2019.3 `org.jetbrains.plugins.cucumber.javascript.CucumberJavaScriptStepDefinitionCreator#createStepDefinition(GherkinStep, PsiFile)` method removed : Use `org.jetbrains.plugins.cucumber.javascript.CucumberJavaScriptStepDefinitionCreator#createStepDefinition(GherkinStep, PsiFile, boolean)` instead. @@ -157,7 +157,7 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h `org.jetbrains.plugins.cucumber.CucumberJvmExtensionPoint#getGlues()` method removed : Java specific method was moved to CucumberJava implementation. -## Changes in DataGrip and Database Tools plugin 2019.3 +## Changes in DataGrip and Database Tools Plugin 2019.3 `com.intellij.sql.dialects.mssql.MssqlDialect` class renamed to `com.intellij.sql.dialects.mssql.MsDialect` : Do not use SQL dialect classes directly. @@ -168,12 +168,12 @@ Please see [Incompatible API Changes](/reference_guide/api_changes_list.md) on h `com.intellij.sql.dialects.postgres.PostgresDialect` class renamed to `com.intellij.sql.dialects.postgres.PgDialect` : Do not use SQL dialect classes directly. -## Changes in RubyMine and Ruby plugin 2019.3 +## Changes in RubyMine and Ruby Plugin 2019.3 `org.jetbrains.plugins.ruby.ruby.codeInsight.types.RubyTypeProvider.createTypeBySymbolFromProviders(Symbol symbol, Context context)` method parameter `Context` removed : This was done as part of [`RUBY-24760`](https://youtrack.jetbrains.com/issue/RUBY-24760) in order to move to new Context-less approach. -## Changes in PyCharm and Python plugin 2019.3 +## Changes in PyCharm and Python Plugin 2019.3 `com.jetbrains.python.inspections.PythonVisitorFilter` class moved to package `com.jetbrains.python.psi` @@ -274,7 +274,7 @@ Recompile your code to pick up the new signature. `com.intellij.openapi.util.KeyedExtensionCollector.getExtensions()` method marked final : Remove custom implementation. -## Changes in DataGrip and Database Tools plugin 2019.1 +## Changes in DataGrip and Database Tools Plugin 2019.1 `com.intellij.sql.psi.SqlTokens.SQL_IDENT` field type changed from `com.intellij.sql.psi.impl.SqlTokenType` to `com.intellij.sql.psi.SqlTokenType` : In most of the cases, it's enough to recompile the code. It may also be needed to check that the code doesn't rely on the field's type. diff --git a/reference_guide/api_changes/api_changes_list_2020.md b/reference_guide/api_changes/api_changes_list_2020.md index 835125805..62a3c626c 100644 --- a/reference_guide/api_changes/api_changes_list_2020.md +++ b/reference_guide/api_changes/api_changes_list_2020.md @@ -150,7 +150,7 @@ Images module functionality (package `org.intellij.images.*`) extracted to plugi } ``` -## Changes in Python plugin 2020.1 +## Changes in Python Plugin 2020.1 `com.jetbrains.python.psi.PyCallExpression.PyMarkedCallee` class removed : Use `com.jetbrains.python.psi.types.PyCallableType` instead. diff --git a/reference_guide/custom_language_support/code_completion.md b/reference_guide/custom_language_support/code_completion.md index c22c2c32b..aece3f123 100644 --- a/reference_guide/custom_language_support/code_completion.md +++ b/reference_guide/custom_language_support/code_completion.md @@ -28,7 +28,7 @@ and a different implementation of [`PsiScopeProcessor`](upsource:///platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) which collects all declarations passed to its `processDeclarations()` method and returns them as an array for filling the completion list. -### Contributor-based Completion +### Contributor-Based Completion Implementing the [`CompletionContributor`](upsource:///platform/analysis-api/src/com/intellij/codeInsight/completion/CompletionContributor.java) diff --git a/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md b/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md index abeda23df..3a92bc68e 100644 --- a/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md +++ b/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md @@ -72,7 +72,7 @@ for [Properties language plugin](upsource:///plugins/properties/) - [Custom Language Support Tutorial: Annotator](/tutorials/custom_language_support/annotator.md) -### External tool +### External Tool Finally, if the custom language employs external tools for validating files in the language (for example, uses the Xerces library for XML schema validation), it can provide an implementation of the [`ExternalAnnotator`](upsource:///platform/analysis-api/src/com/intellij/lang/annotation/ExternalAnnotator.java) @@ -84,7 +84,7 @@ It uses the same [`AnnotationHolder`](upsource:///platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java) interface for converting the output of the external tool into editor highlighting. -## Color settings +## Color Settings The plugin can also provide a configuration interface to allow the user to configure the colors used for highlighting specific items. In order to do that, it should provide an implementation of diff --git a/reference_guide/frameworks_and_external_apis/external_builder_api.md b/reference_guide/frameworks_and_external_apis/external_builder_api.md index dd91611a4..5118b068d 100644 --- a/reference_guide/frameworks_and_external_apis/external_builder_api.md +++ b/reference_guide/frameworks_and_external_apis/external_builder_api.md @@ -43,17 +43,17 @@ A builder may also want to have its custom caches to store additional informatio To pass custom data between the invocation of the same builder between multiple targets, you can use `CompileContext.getUserData()` and `CompileContext.putUserData()`. -### Services and extensions in External Builder +### Services and Extensions in External Builder The external builder process uses the standard Java [services](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) mechanism to support plugins. There are several service interfaces (e.g. [`BuilderService`](upsource:///jps/jps-builders/src/org/jetbrains/jps/incremental/BuilderService.java) which can be implemented in plugins to extend the builder functionality. An implementation of a service need to be registered by creating `META-INF/services/` file containing the qualified name of the implementation class. E.g. `BuilderService` implementations are registered in `META-INF/services/org.jetbrains.jps.incremental.BuilderService` file. These files don't have extensions so you need to map corresponding patterns to text files in IDE settings. -### Registering a plugin for External Builder +### Registering a Plugin for External Builder Sources of a plugin for External Builder should be put in a separate module. By convention such module has name '...-jps-plugin' and its sources are placed under 'jps-plugin' directory in the main plugin directory. Use `com.intellij.compileServer.plugin` extension to add the plugin to classpath of external build process, the plugin jar should be named `.jar`. 'Build' \| 'Prepare Plugin Module for deployment' action will automatically pack 'jps-plugin' part to a separate jar accordingly. -### Debugging a plugin for External Builder +### Debugging a Plugin for External Builder **If your test IDE is IntelliJ IDEA 16.0 or newer** @@ -75,7 +75,7 @@ Start IDE with your plugin with the following VM option After that every time compilation is run in the test IDE, the build process will wait for debugger connection on this port and only then proceed. In working copy of IDE a "Remote" run configuration should be created and pointed to this port. Specifying port "-1" will disable debugging mode. -### Profiling external build process +### Profiling External Build Process The build process has built-in self-cpu-profiling capabilities. To enable them do the following: @@ -96,7 +96,7 @@ as [described here](https://intellij-support.jetbrains.com/hc/en-us/articles/206 Please also provide details about the memory and other VM settings for the build process you were using. -### Accessing External Build process' logs +### Accessing External Build Process' Logs The log file is located under the directory @@ -110,7 +110,7 @@ This file contains logging from all build sessions, including those from the au In IntelliJ Platform versions before version 14.1 log4j configuration was stored in `build-log.xml`. -### Accessing project model and configuration from External Build +### Accessing Project Model and Configuration from External Build The project model in External Build process is provided by JPS (*JetBrains Project System*). A project is represented by [`JpsProject`](upsource:///jps/model-api/src/org/jetbrains/jps/model/JpsProject.java), a module by [`JpsModule`](upsource:///jps/model-api/src/org/jetbrains/jps/model/JpsProject.java) and so on. @@ -118,7 +118,7 @@ If your compiler depends on something that isn't added to the model yet (e.g. so you need to extend the JPS model (use `JpsOsmorcModuleExtension` as a reference implementation) and provide implementation of [`JpsModelSerializerExtension`](upsource:///jps/model-serialization/src/org/jetbrains/jps/model/serialization/JpsModelSerializerExtension.java) to load the configuration from project files. -#### Implementing builder +#### Implementing Builder If your compiler isn't involved into compilation of an existing [`BuildTarget`](upsource:///jps/jps-builders/src/org/jetbrains/jps/builders/BuildTarget.java) you need to create a new implementation of `BuildTarget` and `BuildTargetType`. Also register an implementation of [`BuildTargetScopeProvider`](upsource:///java/compiler/impl/src/com/intellij/compiler/impl/BuildTargetScopeProvider.java) extension on IDE side to add required targets to the build scope. The builder implementation should extend either [`TargetBuilder`](upsource:///jps/jps-builders/src/org/jetbrains/jps/incremental/TargetBuilder.java) or [`ModuleLevelBuilder`](upsource:///jps/jps-builders/src/org/jetbrains/jps/incremental/ModuleLevelBuilder.java) class and should be created using [`BuilderService`](upsource:///jps/jps-builders/src/org/jetbrains/jps/incremental/BuilderService.java) extension. diff --git a/reference_guide/frameworks_and_external_apis/external_system_integration.md b/reference_guide/frameworks_and_external_apis/external_system_integration.md index c69d22b5c..aaccd4438 100644 --- a/reference_guide/frameworks_and_external_apis/external_system_integration.md +++ b/reference_guide/frameworks_and_external_apis/external_system_integration.md @@ -18,9 +18,9 @@ There are multiple project management systems ([Apache Maven](https://maven.apac That means that we can separate external system-specific logic and general IDE processing. *'External system'* sub-system provides simple API for wrapping external system and extensible IDE-specific processing logic. -# Project management +# Project Management -## Project data domain +## Project Data Domain **General** External system wrapper is required to be able to build project info on the basis of the given external system config. That information is built using in terms of [`DataNode`](upsource:///platform/external-system-api/src/com/intellij/openapi/externalSystem/model/DataNode.java), [`Key`](upsource:///platform/external-system-api/src/com/intellij/openapi/externalSystem/model/Key.java) and [`ExternalEntityData`](upsource:///platform/external-system-api/src/com/intellij/openapi/externalSystem/model/project/ExternalEntityData.java). @@ -37,7 +37,7 @@ For example, simple one-module project might look as below: **Consequence** The IDE provides a set of built-in *Key*s and *ExternalEntityData*s but any external system integration or third-party plugin developer might enhance project data by defining her own *Key* and *ExternalEntityData* and storing them at a child of appropriate *DataNode*. -## Managing project data +## Managing Project Data We need to process project data is built on external system config basis. Here comes [`ProjectDataService`](upsource:///platform/external-system-api/src/com/intellij/openapi/externalSystem/service/project/manage/ProjectDataService.java). It is a strategy which knows how to manage particular *ExternalEntityData*. For example, when we want to import a project from external model, we can start by the top level *DataNode* which references project info and then import its data using corresponding service. @@ -45,7 +45,7 @@ Custom services can be defined via *'externalProjectDataService'* extension. The good thing is that we can separate project parsing and management here. That means that a set of *DataNode*, *Key* and *ProjectDataServices* can be introduced for particular technology and then every external system integration can build corresponding data if necessary using it. -## Importing from external model +## Importing from External Model IntelliJ platform provides standard API for that. Namely, [`ProjectImportBuilder`](upsource:///java/idea-ui/src/com/intellij/projectImport/ProjectImportBuilder.java) and [`ProjectImportProvider`](upsource:///java/idea-ui/src/com/intellij/projectImport/ProjectImportProvider.java). There are two classes built on *template method* pattern - [`AbstractExternalProjectImportBuilder`](upsource:///java/idea-ui/src/com/intellij/openapi/externalSystem/service/project/wizard/AbstractExternalProjectImportBuilder.java) and [`AbstractExternalProjectImportProvider`](upsource:///java/idea-ui/src/com/intellij/openapi/externalSystem/service/project/wizard/AbstractExternalProjectImportProvider.java). Concrete implementations are registered in `plugin.xml`. @@ -56,7 +56,7 @@ Here is an example from the gradle integration plugin: Note that [`AbstractExternalProjectImportBuilder`](upsource:///java/idea-ui/src/com/intellij/openapi/externalSystem/service/project/wizard/AbstractExternalProjectImportBuilder.java) is built on top of the 'external system settings' controls. -## Auto-import +## Auto-Import It's possible to configure external system integration to automatically refresh project structure when external project's config files are modified. @@ -68,7 +68,7 @@ Describe project's settings files to track by having external system `ExternalSy > **NOTE** `ExternalSystemAutoImportAware.getAffectedExternalProjectPath()` is called quite often, that’s why it’s expected to return control as soon as possible. Helper `CachingExternalSystemAutoImportAware` class might be used for caching, i.e. `ExternalSystemManager` which implements `ExternalSystemAutoImportAware` can have a field like `new CachingExternalSystemAutoImportAware(new MyExternalSystemAutoImportAware())` and delegate `ExternalSystemAutoImportAware.getAffectedExternalProjectPath()` calls to it. -### Auto-Import for standalone external systems +### Auto-Import for Standalone External Systems Some external systems don’t have `ExternalSystemManager` (e.g., Maven), but they also can use auto-import core to track changes in settings files. For this, implement `ExternalSystemProjectAware` interface that describes settings files for tracking and an action to reload project model. Then register the instance with `ExternalSystemProjectTracker` to start tracking. @@ -76,7 +76,7 @@ Then register the instance with `ExternalSystemProjectTracker` to start tracking > **NOTE** Multiple `ExternalSystemProjectAware` instances can correspond to a single external system. It allows performing project reload differently depending on the set of settings files (project aware per settings file, per module, per external project, etc.). -### Icon for reload notification +### Icon for Reload Notification Since 2020.1, the icon for reload notification can be specified per external system. Implement `ExternalSystemIconProvider` and register via `com.intellij.externalIconProvider` extension point in `plugin.xml`. Alternatively, set `reloadIcon` field external system implements `ExternalSystemIconProvider` directly. diff --git a/reference_guide/frameworks_and_external_apis/spring_api.md b/reference_guide/frameworks_and_external_apis/spring_api.md index f1df0231e..deffbea03 100644 --- a/reference_guide/frameworks_and_external_apis/spring_api.md +++ b/reference_guide/frameworks_and_external_apis/spring_api.md @@ -36,7 +36,7 @@ Please use only Spring-related functionality exposed in `spring-api.jar` (where Add `com.intellij.spring` to your `plugin.xml` to require "Spring Support" plugin to be activated. All available extension points are provided under `com.intellij.spring` prefix. Note that "Spring Support" plugin itself has dependencies to a few other plugins which need to be enabled in your sandbox (see notifications on startup). -## Main concepts +## Main Concepts A Spring facet can be attached on a Module. (Nearly) All Spring functionality requires an existing and properly setup Spring facet. Spring facets usually contain one more user-configured or automatically provided filesets, which group a set of Spring related configuration files (XML, Code, .properties or other configuration files). @@ -45,14 +45,14 @@ A fileset usually corresponds to an actual application context configuration at As an API-user, you will usually rather work with `SpringModel` (which is built on top of fileset(s)). -## API updates +## API Updates > **Note** 2017.3: `LocalXmlModel#setActiveProfiles` & `LocalAnnotationModel#setActiveProfiles` have been deprecated and will be removed in 2018.1. > **Note** Starting with 2016.2, internal representation of bean _type_ has been changed from `PsiClass` to `PsiType`, please note deprecations. > **Note** Some core classes have been changed in 14(.1), please see "_Version 14(.1)_" notes for info on how to replace existing API-calls. -## How do I... +## How Do I... ### Spring Setup To check availability of Spring/Spring Facet etc. see `com.intellij.spring.model.utils.SpringCommonUtils`. @@ -61,25 +61,25 @@ _2016.2_ See `com.intellij.spring.SpringLibraryUtil` to obtain information about ### Spring Model -##### Obtain Spring Model by file, PsiElement, .. +##### Obtain Spring Model by File, PsiElement, ... See `SpringManager#getSpringModel(s)...` and `com.intellij.spring.model.utils.SpringModelUtils`. -##### Contribute implicit model(s) +##### Contribute Implicit Model See `com.intellij.spring.SpringModelProvider` to provide implicit filesets (e.g. provided by another framework in specific configuration file). _Version 15_ See `com.intellij.spring.facet.SpringAutodetectedFileSet` for a convenient base class. Please note that autodetected filesets cannot be edited/modified by users in Spring facet. -##### Customize implicit models configuration +##### Customize Implicit Models Configuration _2017.1_ See `com.intellij.spring.facet.SpringFileSetEditorCustomization` to customize presentation and/or add extra settings/actions for specific autodetected filesets. -##### Contribute implicit beans +##### Contribute Implicit Beans See `com.intellij.spring.model.jam.CustomComponentsDiscoverer` or `com.intellij.spring.model.SpringImplicitBeansProviderBase` to provide implicit (framework-specific) beans (e.g. "servletContext" by Spring MVC). _Version 15_ `CustomComponentsDiscoverer` has been split into `com.intellij.spring.model.custom.CustomLocalComponentsDiscoverer` and `com.intellij.spring.model.custom.CustomModuleComponentsDiscoverer` respectively. -##### Contribute custom bean scope +##### Contribute Custom Bean Scope _Version 14_ See `com.intellij.spring.model.scope.SpringCustomBeanScope` to provide custom (e.g. framework specific) bean scopes. @@ -89,34 +89,34 @@ _Version 14.1_ ### Beans -##### Search for bean by name +##### Search for Bean by Name `com.intellij.spring.CommonSpringModel#findBeanByName` _Version 14_: `com.intellij.spring.model.utils.SpringModelSearchers#findBean` -##### Search for beans by type +##### Search for Beans by Type Choose one of `com.intellij.spring.CommonSpringModel#findBeansByPsiClassXXX` variants (please note deprecated methods). _Version 14_: `com.intellij.spring.model.utils.SpringModelSearchers#findBeans` _Version 16_: note deprecation of `SpringModelSearchParameters.BeanClass#withInheritors(GlobalSearchScope)` -##### Find out if bean with given name/type exists +##### Find out if Bean with Given Name/Type Exists _Version 14_: `com.intellij.spring.model.utils.SpringModelSearchers#doesBeanExist` (please note deprecated methods) -##### Mark bean as infrastructure bean +##### Mark Bean as Infrastructure Bean _Version 14_: implement `SpringInfrastructureBean`, such beans obtain special icon and can be filtered in various places in UI. ### XML Configuration All support for XML-based Spring configuration files is provided via [DOM-API](xml_dom_api.md). -##### Add support for additional Spring namespace +##### Add Support for Additional Spring Namespace See EP `com.intellij.spring.dom.SpringCustomNamespaces`, registered namespace-key must match the one registered with your DOM elements via `@Namespace`. Register available elements via standard `DomExtender` EP or `com.intellij.spring.dom.SpringCustomNamespaces#registerExtensions` (Version 14). Please pay attention to `getModelVersion` and `getStubVersion` (see javadoc). -##### Add reference to Spring Bean in my DomElement +##### Add Reference to Spring Bean in DomElement Use the following template: ```java @@ -128,7 +128,7 @@ GenericAttributeValue getMyAttributeName(); ### Code Configuration -##### Add reference to Spring Bean in my JamElement +##### Add Reference to Spring Bean in JamElement _Version 14_ ```java @@ -145,16 +145,16 @@ See `com.intellij.spring.model.aliasFor.SpringAliasForUtils` to obtain correspon _Version 15_ See `com.intellij.spring.spi.SpringSpiManager`. -### IDE features +### IDE Features -##### Add inspections to Spring Validator +##### Add Inspections to Spring Validator Add additional inspections (e.g. for custom namespace) to Spring Validator (*Settings|Compiler|Validation*) via EP `com.intellij.spring.SpringInspectionsRegistry$Contributor`. -##### Add additional files to Spring Validator +##### Add Additional Files to Spring Validator _Version 14.1_ Additional files to be processed by inspections registered with Spring Validator (e.g. specific `.properties` configuration files) can be registered via `com.intellij.spring.SpringInspectionsRegistry$AdditionalFilesContributor` -##### Configure Spring support for other frameworks +##### Configure Spring Support for Other Frameworks Use `com.intellij.spring.facet.SpringConfigurator` to provide "automatic" configuration when Spring facet is added via framework wizard. ##### UI/Presentation @@ -187,7 +187,7 @@ Use `com.intellij.spring.boot.library.SpringBootLibraryUtil` to query version an ### Custom Configuration Files Format `com.intellij.spring.boot.model.SpringBootModelConfigFileContributor` allows to add support for custom config file formats. -### Auto-Configuration support +### Auto-Configuration Support Existing `Condition` implementations can be simulated at design time in IDE via `com.intellij.spring.boot.model.autoconfigure.conditions.ConditionalContributor`. Custom `@ConditionalOn...` annotations implementing `com.intellij.spring.boot.model.autoconfigure.conditions.jam.ConditionalOnJamElement` will be added into evaluation automatically. @@ -197,7 +197,7 @@ requires `spring-boot-initializr.jar` `com.intellij.spring.boot.initializr.SpringInitializrModuleBuilderPostTask` allows to perform custom setup steps after creation of module (e.g. setup integration with build system). -### Endpoint tab +### Endpoint Tab _2018.2_ - requires `spring-boot-run.jar` Use EP `com.intellij.spring.boot.run.endpoint` to add custom actuator endpoint tabs. Any settings should be exposed in "Spring Boot" settings tab via `com.intellij.spring.boot.run.endpointTabConfigurable` EP. \ No newline at end of file diff --git a/reference_guide/frameworks_and_external_apis/xml_dom_api.md b/reference_guide/frameworks_and_external_apis/xml_dom_api.md index 5634ffd88..9e3aa0424 100644 --- a/reference_guide/frameworks_and_external_apis/xml_dom_api.md +++ b/reference_guide/frameworks_and_external_apis/xml_dom_api.md @@ -275,7 +275,7 @@ You can extend existing DOM model at runtime by implementing `com.intellij.util. If the contributed elements depend on anything other than plain XML file content (used framework version, libraries in classpath, ...), make sure to return `false` from `DomExtender.supportsStubs()`. -### Generating DOM from existing XSD +### Generating DOM from Existing XSD DOM can be generated automatically from existing XSD/DTD. Output correctness/completeness will largely depend on the input scheme and may require additional manual adjustments. Follow these steps: @@ -285,7 +285,7 @@ Follow these steps: * Select Scheme file and set options, then click "Generate" to generate sources * Modify generated sources according to your needs -### IDE support +### IDE Support _Plugin DevKit_ supports the following features for working with DOM related code: * [`DomElement`](upsource:///xml/dom-openapi/src/com/intellij/util/xml/DomElement.java) - provide implicit usages for all DOM-related methods defined in inheriting classes (to suppress "unused method" warning) @@ -347,7 +347,7 @@ If you want to be notified on every change in the DOM model, add `DomEventListen #### Highlighting Annotations The DOM supports error checking and highlighting. It's based on annotations which you add to the DOM element in a special place (don't confuse these annotations with the ones of Java 5 — they are very different). You need to implement the [`DomElementAnnotator`](upsource:///xml/dom-openapi/src/com/intellij/util/xml/highlighting/DomElementsAnnotator.java) interface, and override `DomFileDescription.createAnnotator()` method, and create this annotator there. In `DomElementsAnnotator.annotate(DomElement element, DomElementsProblemsHolder annotator)` you should report about all errors and warnings in the element's sub-tree to the annotator (`DomElementsProblemsHolder.createProblem()`). You should return this annotator in the corresponding virtual method of the `DomFileDescription`. -#### Automatic highlighting (BasicDomElementsInspection) +#### Automatic Highlighting (BasicDomElementsInspection) The following errors can be highlighted automatically by providing an instance of `BasicDomElementsInspection`: - `@Required` element missing or having empty text @@ -418,7 +418,7 @@ The case just described is simple, but rare. More often, you really have to inco Now you only have to let DOM know that you wish to use this implementation every time you're creating a model element that should implement the necessary interface. Simply register it using extension point `com.intellij.dom.implementation` and DOM will generate at run-time the class that not only implements the needed interface, but also extends your abstract class. -### Models across multiple files +### Models Across Multiple Files Many frameworks require a set of XML configuration files ("fileset") to work as one model, so resolving/navigation works across all related DOM files. Depending on implementation/plugin, providing filesets implicitly (using existing framework's setup in project) or via user configuration (usually via dedicated `Facet`) can be achieved. @@ -431,7 +431,7 @@ Example can be found in Struts 2 plugin (package `com.intellij.struts2.dom.strut DOM elements can be stubbed, so (costly) access to XML/PSI is not necessary (see [Indexing and PSI Stubs](/basics/indexing_and_psi_stubs.md) for similar feature for custom languages). Performance relevant elements, tag or attribute getters can simply be annotated with `@com.intellij.util.xml.Stubbed`. Return `true` from `DomFileDescription.hasStubs()` and increase `DomFileDescription.getStubVersion()` whenever you change `@Stubbed` annotations usage in your DOM hierarchy to trigger proper rebuilding of Stubs during indexing. -## Building a DOM-based GUI +## Building a DOM-Based GUI ### Forms All forms that deal with DOM are organized in a special way. They support two main things: getting data from XML into the UI, and saving UI data to XML. The former is called resetting, the latter — committing. There's [`Committable`](upsource:///xml/dom-openapi/src/com/intellij/util/xml/ui/Committable.java) interface that has corresponding methods: `commit()` and `reset()`. There's also a way of structuring your forms into smaller parts, namely the Composite pattern: [`CompositeCommittable`](upsource:///xml/dom-openapi/src/com/intellij/util/xml/ui/CompositeCommittable.java). Methods `commit()` and `reset()` are invoked automatically on editor tab switch or undo. So you only need to ensure that all your Swing structure is organized in a tree of `CompositeCommittable`, and all the hard work will be done by the IDE. @@ -460,7 +460,7 @@ The control is bound to a non-editable `JComboBox`, so it can be used to choose ##### BooleanEnumControl Sometimes, when there are only 2 alternatives, it's convenient to use a check box instead of combo box. This control is designed specially for such cases. While being (and being bound to) a check box, the control edits not just "true" or "false", but any two String values, or two enum elements. In the last case, it has a boolean _invertedOrder_ parameter, to specify which element corresponds to the checked state. By default _invertedOrder_ is set to `false`, so the first element corresponds to the unchecked state, and the second — to the checked one. If you set the parameter to `true`, the states will swap. -### Editor-based Controls +### Editor-Based Controls Please note that editor-based controls are built on IntelliJ Platform's `Editor` instead of standard `JTextField`. Since there's currently no way to instantiate Editor directly through the Open API, controls are bound to special `JPanel` inheritors, and their `bind()` method adds the necessary content to those panels. ##### TextControl diff --git a/reference_guide/messaging_infrastructure.md b/reference_guide/messaging_infrastructure.md index cf7008704..9f7951126 100644 --- a/reference_guide/messaging_infrastructure.md +++ b/reference_guide/messaging_infrastructure.md @@ -1,5 +1,5 @@ --- -title: Messaging infrastructure +title: Messaging Infrastructure --- @@ -28,7 +28,7 @@ This class serves as an endpoint at the messaging infrastructure. I.e. clients a * *listener class* that is a business interface for particular topic. Subscribers register implementation of this interface at the messaging infrastructure and publishers may later retrieve object that conforms (IS-A) to it and call any method defined there. Messaging infrastructure takes care on dispatching that to all subscribers of the topic, i.e. the same method with the same arguments will be called on the registered callbacks; -## Message bus +## Message Bus Is the core of the messaging system. Is used at the following scenarios: @@ -52,7 +52,7 @@ Also it can be plugged to standard semi-automatic disposing [`Disposable`](upsource:///platform/util/src/com/intellij/openapi/Disposable.java) ); -## Putting altogether +## Putting Altogether *Defining business interface and topic* @@ -157,7 +157,7 @@ Broadcast configuration is defined per-topic. Following options are available: * _TO\_PARENT_; -# Nested messages +# Nested Messages _Nested message_ is a message sent (directly or indirectly) during another message processing. The IntelliJ Platform's Messaging infrastructure guarantees that all messages sent to particular topic will be delivered at the sending order. @@ -182,7 +182,7 @@ Let's see what happens if someone sends a message to the target topic: # Tips'n'tricks -## Relief listeners management +## Relief Listeners Management Messaging infrastructure is very light-weight, so, it's possible to reuse it at local sub-systems in order to relief [Observers](https://en.wikipedia.org/wiki/Observer_pattern) construction. Let's see what is necessary to do then: @@ -201,7 +201,7 @@ Let's compare that with a manual implementation: 4. Manually iterate all listeners and call target callback in all places where new event is fired; -## Avoid shared data modification from subscribers +## Avoid Shared Data Modification from Subscribers We had a problem in a situation when two subscribers tried to modify the same document ([IDEA-71701](https://youtrack.jetbrains.com/issue/IDEA-71701)). diff --git a/reference_guide/multiple_carets.md b/reference_guide/multiple_carets.md index 4f4eed4e9..7888e1352 100644 --- a/reference_guide/multiple_carets.md +++ b/reference_guide/multiple_carets.md @@ -1,5 +1,5 @@ --- -title: Supporting multiple carets +title: Supporting Multiple Carets --- @@ -12,7 +12,7 @@ When after some action two or more carets end up in the same visual position, th There's a concept of 'primary' caret — the one on which non-multi-caret-aware actions and the actions which need a single-point document context (like code completion) will operate. Currently, the most recent caret is considered the primary one. -## Core functionality +## Core Functionality Core logic related to multi-caret implementation such as accessing currently existing carets, adding and removing carets, is available via [`CaretModel`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java) @@ -30,7 +30,7 @@ So the behaviour of legacy code (not using Caret interface) will depend on the c Correspondingly, block-selection-related methods in SelectionModel interface have changed behaviour — `hasBlockSelection()` will always return false, `setBlockSelection()` will create a multi-caret selection equivalent to the requested block selection. `getBlockSelectionStarts()` and `getBlockSelectionEnds()` methods work in multi-caret state, returning all selected regions. -## Editor actions +## Editor Actions ### EditorAction and EditorActionHandler @@ -41,7 +41,7 @@ Of course, the handler can just ignore the caret parameter if its functionality If the handler needs to implement multi-caret functionality it can do so explicitly in the overridden `doExecute` method, but if it just needs that method to be invoked for each caret, it suffices to pass a parameter to `EditorActionHandler` constructor to make `doExecute` called for each caret when the handler is invoked without a specific caret context. -### Editor action delegates +### Editor Action Delegates The following delegates are available: @@ -56,7 +56,7 @@ The following delegates are available: At the moment there's no need to make any changes in the handlers to support multiple carets — they are already invoked for each caret. -## Typing actions +## Typing Actions ### TypedActionHandler, TypedHandlerDelegate @@ -84,7 +84,7 @@ needs to be provided instead. ----------- -## Code insight actions +## Code Insight Actions Existing actions inheriting from [`CodeInsightAction`](upsource:///platform/lang-api/src/com/intellij/codeInsight/actions/CodeInsightAction.java) will work for primary caret only. diff --git a/reference_guide/performance/performance.md b/reference_guide/performance/performance.md index 0bc117f5a..d0da06093 100644 --- a/reference_guide/performance/performance.md +++ b/reference_guide/performance/performance.md @@ -3,9 +3,11 @@ title: Optimizing Performance --- -## Working with PSI efficiently +## Working with PSI Efficiently -#### Avoid `PsiElement` methods which are expensive with deep trees +#### Avoid Expensive Methods in `PsiElement` + +Avoid `PsiElement` methods which are expensive with deep trees. `getText()` traverses the whole tree under the given element and concatenates strings, consider `textMatches()` instead. @@ -15,8 +17,9 @@ File and project often can be computed once per some analysis and then stored in Additionally, `getText()`, `getNode()`, `getTextRange()`, etc., all need AST, which can be quite an expensive operation. See below. -#### Avoid loading too many parsed trees or documents into memory at the same time +#### Avoid Using Many PSI Trees/Documents +Avoid loading too many parsed trees or documents into memory at the same time. Ideally, only AST nodes from files open in the editor should be present in the memory. Everything else, even if it's needed for resolve/highlighting purposes, can be accessed via PSI interfaces, but its implementations should [use stubs](/basics/indexing_and_psi_stubs/stub_indexes.md) underneath, which are less CPU- and memory-expensive. @@ -33,7 +36,7 @@ need documents, consider saving the information you need to provide in a [custom If you still need documents, then at least ensure you load them one by one and don't hold them on strong references to let GC free the memory as quickly as possible. -#### Cache results of heavy computations +#### Cache Results of Heavy Computations These include `PsiElement.getReference(s)`, `PsiReference.resolve()` (and `multiResolve()` and other equivalents), expression types, type inference results, control flow graphs, etc. @@ -44,9 +47,9 @@ If the information you cache depends only on a subtree of the current PSI elemen (and nothing else: no resolve results or other files), you can cache it in a field in that `PsiElement` and drop the cache in an override of `ASTDelegatePsiElement.subtreeChanged()`. -## Improving indexing performance +## Improving Indexing Performance -#### Avoid using AST +#### Avoid Using AST Use lexer information instead of parsed trees if possible. @@ -56,14 +59,14 @@ Make sure to traverse only the nodes you need to. For stub index, implement [`LightStubBuilder`](upsource:///platform/core-impl/src/com/intellij/psi/stubs/LightStubBuilder.java). For other indices, you can get the light AST manually via `((PsiDependentFileContent) fileContent).getLighterAST()`. -#### Consider prebuilt stubs +#### Consider Prebuilt Stubs If your language has a massive standard library, which is mostly the same for all users, you can avoid stub-indexing it in each installation by providing prebuilt stubs with your distribution. See [`PrebuiltStubsProvider`](upsource:///platform/lang-impl/src/com/intellij/psi/stubs/PrebuiltStubs.kt) extension. -## Avoiding UI freezes +## Avoiding UI Freezes -#### Don't perform long operations in UI thread +#### Do not Perform Long Operations in UI Thread In particular, don't traverse VFS, parse PSI, resolve references or query `FileBasedIndex`. diff --git a/reference_guide/project_model/facet.md b/reference_guide/project_model/facet.md index e0bbc4934..b53b488ec 100644 --- a/reference_guide/project_model/facet.md +++ b/reference_guide/project_model/facet.md @@ -16,5 +16,5 @@ Please see [Facet Basics](https://github.com/JetBrains/intellij-sdk-docs/tree/ma ### Managing Facets To create, search and access the list of facets for a module use [`FacetManager`](upsource:///platform/lang-api/src/com/intellij/facet/FacetManager.java). -### Facet-based Tool Window +### Facet-Based Tool Window A [tool window](/user_interface_components/tool_windows.md) dependent on the existence of given facet(s) can be registered via `com.intellij.facet.toolWindow` extension point. diff --git a/reference_guide/project_model/module.md b/reference_guide/project_model/module.md index d5a331017..c3e491a5b 100644 --- a/reference_guide/project_model/module.md +++ b/reference_guide/project_model/module.md @@ -101,7 +101,7 @@ String moduleName = module == null ? "Module not found" : module.getName(); * To get the project module to which the specified [PSI element](/basics/architectural_overview/psi_elements.md) belongs, use the `ModuleUtil.findModuleForPsiElement()` method. -### Accessing module roots +### Accessing Module Roots Information about module roots can be accessed via [`ModuleRootManager`](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java). For example, the following snippet shows how to access the content roots of a module: @@ -110,7 +110,7 @@ For example, the following snippet shows how to access the content roots of a mo VirtualFile[] contentRoots = ModuleRootManager.getInstance(module).getContentRoots(); ``` -### Checking belonging to a module source root +### Checking Belonging to a Module Source Root To check if a virtual file or directory belongs to a module source root, use the `ProjectFileIndex.getSourceRootForFile()` method. This method returns `null` if the file or directory does not belong to any source root of modules in the project. @@ -118,7 +118,7 @@ To check if a virtual file or directory belongs to a module source root, use the VirtualFile moduleSourceRoot = ProjectRootManager.getInstance(project).getFileIndex().getSourceRootForFile(virtualFileOrDirectory); ``` -## Receiving notifications about module changes +## Receiving Notifications About Module Changes To receive notifications about module changes (modules being added, removed or renamed), use the [message bus](/reference_guide/messaging_infrastructure.md) and the `ProjectTopics.MODULES` topic: diff --git a/reference_guide/project_model/project.md b/reference_guide/project_model/project.md index f38e44682..749584dbd 100644 --- a/reference_guide/project_model/project.md +++ b/reference_guide/project_model/project.md @@ -78,7 +78,7 @@ changes need to be performed in a [write action](/basics/architectural_overview/ Refer to the [project_model](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/project_model/src/main/java/org/intellij/sdk/project/model/ModificationAction.java) code sample to learn how project structure modification can be implemented. -## Receiving Notifications about Project Structure Changes +## Receiving Notifications About Project Structure Changes To receive notifications about changes in project structure (modules or libraries being added or removed, module dependencies being changed, and so on), use the [message bus](/reference_guide/messaging_infrastructure.md) and the `ProjectTopics.PROJECT_ROOTS` topic: ```java diff --git a/reference_guide/ui_themes/themes_customize.md b/reference_guide/ui_themes/themes_customize.md index f18d3bc93..000a6a2e1 100644 --- a/reference_guide/ui_themes/themes_customize.md +++ b/reference_guide/ui_themes/themes_customize.md @@ -283,6 +283,6 @@ It appears as the _Since_ attribute in editor popups. In the Quick Documentation popup the format is e.g. _Since: 2019.2_. The Code Completion popup is similar, but it the format is e.g. _[Since 2019.2]_. -### Finding a UI Control Key using Laf Defaults UI +### Finding a UI Control Key Using Laf Defaults UI Using the [Laf Defaults](/reference_guide/internal_actions/internal_ui_lafd.md) inspector, enter the `element` portion of the key. The Laf Defaults inspector will prompt with a list of UI Control keys and their default color. diff --git a/reference_guide/ui_themes/themes_metadata.md b/reference_guide/ui_themes/themes_metadata.md index 890f6b4e9..794c95a51 100644 --- a/reference_guide/ui_themes/themes_metadata.md +++ b/reference_guide/ui_themes/themes_metadata.md @@ -141,7 +141,7 @@ If a component has a gradient color, add the words “start” and “end” for #### Capitalization Capitalize Object and SubObject. Use lowerCamelCase for property. -#### Do not use +#### Do Not Use | Do not use | Use instead | |------------|-------------| @@ -150,7 +150,7 @@ Capitalize Object and SubObject. Use lowerCamelCase for property. | `Text` | `Foreground` | | `darcula` _and other look-and-feel names_ | _Omit_ | -#### Swing legacy +#### Swing Legacy Some color keys are not named according to the rules above. Such keys are inherited from Java Swing and cannot be renamed for compatibility reasons. Do not use naming patterns from the legacy keys. diff --git a/reference_guide/work_with_icons_and_images.md b/reference_guide/work_with_icons_and_images.md index 106005832..d5a63fadc 100644 --- a/reference_guide/work_with_icons_and_images.md +++ b/reference_guide/work_with_icons_and_images.md @@ -38,7 +38,7 @@ Use these constants inside `plugin.xml` as well. Note that the package name `ico icon="DemoPluginIcons.DEMO_ACTION"/> ``` -### Image formats +### Image Formats IntelliJ Platform supports Retina displays and has dark theme called Darcula. Thus, every icon should have a dedicated variant for Retina devices and Darcula theme. In some cases, you can skip dark variants if the original icon looks good under Darcula. @@ -51,7 +51,7 @@ Required icon sizes depend on the usage as listed in the following table: | Editor gutter | 12x12 | -#### SVG format +#### SVG Format > **NOTE** SVG icons are supported since 2018.2. As SVG icons can be scaled arbitrarily, they provide better results on HiDPI environments or when used in combination with bigger screen fonts (e.g., in presentation mode). @@ -68,7 +68,7 @@ A minimal SVG icon file: The naming notation used for PNG icons (see below) is still relevant. However, the `@2x` version of an SVG icon should still provide the same base size. The icon graphics of such an icon can be expressed in more details via double precision. If the icon graphics are simple enough so that it renders perfectly in every scale, then the `@2x` version can be omitted. -#### PNG format +#### PNG Format > **NOTE** Please consider using SVG icons if your plugin targets 2018.2+. All icon files must be placed in the same directory following this naming pattern (replace `.png` with `.svg` for SVG icons): diff --git a/tutorials/build_system/gradle_guide.md b/tutorials/build_system/gradle_guide.md index bdc111888..1a54d29d3 100644 --- a/tutorials/build_system/gradle_guide.md +++ b/tutorials/build_system/gradle_guide.md @@ -70,7 +70,7 @@ Every version of the IntelliJ Platform has a corresponding version of the [JetBr A different version of the runtime can be used by specifying the `runIde.jbrVersion` attribute, describing a version of the JetBrains Runtime that should be used by the IDE Development Instance. The Gradle plugin will fetch the specified JetBrains Runtime as needed. -### Managing Directories used by the Gradle Plugin +### Managing Directories Used by the Gradle Plugin There are several attributes to control where the Gradle plugin places directories for downloads and for use by the IDE Development Instance. The location of the [sandbox home](/basics/ide_development_instance.md#sandbox-home-location-for-gradle-based-plugin-projects) directory and its subdirectories can be controlled with Gradle plugin attributes. diff --git a/tutorials/build_system/prerequisites.md b/tutorials/build_system/prerequisites.md index ff441a429..c88311a5a 100644 --- a/tutorials/build_system/prerequisites.md +++ b/tutorials/build_system/prerequisites.md @@ -173,7 +173,7 @@ Gradle projects are run from the IDE's Gradle Tool window. Before running [`my_gradle_project`](#components-of-a-wizard-generated-gradle-intellij-platform-plugin), some code could be added to provide simple functionality. See the [Creating Actions](/tutorials/action_system/working_with_custom_actions.md) tutorial for step-by-step instructions for adding a menu action. -### Executing the plugin +### Executing the Plugin Open the Gradle tool window and search for the `runIde` task: * If it’s not in the list, hit the [Refresh](https://www.jetbrains.com/help/idea/jetgradle-tool-window.html#1eeec055) button at the top of the Gradle window. * Or [Create a new Gradle Run Configuration](https://www.jetbrains.com/help/idea/create-run-debug-configuration-gradle-tasks.html). diff --git a/tutorials/custom_language_support/code_style_settings.md b/tutorials/custom_language_support/code_style_settings.md index c8f15faaa..d053af0a9 100644 --- a/tutorials/custom_language_support/code_style_settings.md +++ b/tutorials/custom_language_support/code_style_settings.md @@ -51,7 +51,7 @@ The `SimpleLanguageCodeStyleSettingsProvider` implementation is registered with ``` -## 16.6. Run the project +## 16.6. Run the Project In the IDE Development Instance, open the Simple Language code formatting page: **Preferences/Settings \| Editor \| Code Style \| Simple**. ![Code Style Settings](img/code_style_settings.png) diff --git a/tutorials/custom_language_support/quick_fix.md b/tutorials/custom_language_support/quick_fix.md index d3c798176..c74cfb146 100644 --- a/tutorials/custom_language_support/quick_fix.md +++ b/tutorials/custom_language_support/quick_fix.md @@ -35,7 +35,7 @@ This method call registers the `SimpleCreatePropertyQuickFix` as the Intention A {% include /code_samples/simple_language_plugin/src/main/java/org/intellij/sdk/language/SimpleAnnotator.java %} ``` -## 18.4. Run the project +## 18.4. Run the Project Open the test [Java file](/tutorials/custom_language_support/annotator.md#run-the-project) in an IDE Development Instance running the `simple_language_plugin`. To test `SimpleCreatePropertyQuickFix`, change `simple:website` to `simple:website.url`. diff --git a/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md b/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md index 6e8929094..c93851c2d 100644 --- a/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md +++ b/tutorials/custom_language_support/syntax_highlighter_and_color_settings_page.md @@ -60,7 +60,7 @@ Register the Simple Language color settings page with the IntelliJ Platform in t ``` -### 5.7. Run the project +### 5.7. Run the Project In the IDE Development Instance, open the Simple Language highlight settings page: **Preferences/Settings \| Editor \| Color Scheme \| Simple**. Each color initially inherits from a _Language Defaults_ value. diff --git a/tutorials/framework.md b/tutorials/framework.md index a962cbaef..3909d77ae 100644 --- a/tutorials/framework.md +++ b/tutorials/framework.md @@ -6,7 +6,7 @@ title: Supporting Frameworks The following tutorial shows how to support a custom framework type for a project and make this framework type embedded in a project wizard as a UI component.n The examples in this tutorial rely heavily on the [framework_basics](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/framework_basics) code sample. -## 1. Creating a new framework +## 1. Creating a New Framework In oder to make a custom framework available and configurable for a project the [`FrameworkTypeEx`](upsource:///java/idea-ui/src/com/intellij/framework/FrameworkTypeEx.java) class needs to be extended, in this example to make the [DemoFramework](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/framework_basics/src/main/java/org/intellij/sdk/framework/DemoFramework.java) class. ```java @@ -14,7 +14,7 @@ public class DemoFramework extends FrameworkTypeEx { } ``` -## 2. Registering framework +## 2. 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-docs/blob/master/code_samples/framework_basics/src/main/resources/META-INF/plugin.xml) configuration file: @@ -25,7 +25,7 @@ configuration file: ``` -## 3. Setting up mandatory attributes +## 3. Setting up Mandatory Attributes The framework component should have a unique name passed as a string literal to the constructor. It is best if this is the FQN name of the class: @@ -56,7 +56,7 @@ public class DemoFramework extends FrameworkTypeEx { } ``` -## 4. Creating provider for enabling framework support +## 4. Creating Provider for Enabling Framework Support To make the framework set up available while executing the steps to create a project, the `DemoFramework.createProvider()` method must be implemented to return an object of type [`FrameworkSupportInModuleConfigurable`](upsource:///java/idea-ui/src/com/intellij/framework/addSupport/FrameworkSupportInModuleConfigurable.java), which adds the framework to a module. In this example the framework is added to any [`ModuleType`](upsource:///platform/lang-api/src/com/intellij/openapi/module/ModuleType.java) without checking, which is usually not the case. diff --git a/tutorials/kotlin.md b/tutorials/kotlin.md index 2014b58aa..47b77a458 100644 --- a/tutorials/kotlin.md +++ b/tutorials/kotlin.md @@ -67,7 +67,7 @@ repositories { Please note that you should **not** include `kotlin-runtime` and `kotlin-stdlib` jars with your plugin because Kotlin guarantees backward- and forward- binary compatibility. -### 3.1. Use Kotlin to write Gradle script +### 3.1. Use Kotlin to Write Gradle Script Starting with 4.4, Gradle supports `build.gradle.kts`, an alternative to `build.gradle` written in Kotlin. @@ -100,7 +100,7 @@ intellij { The best way to create user interfaces with Kotlin is to use a [type safe DSL](/user_interface_components/kotlin_ui_dsl.md) for building forms. Using GUI designer with Kotlin is currently [not supported](https://youtrack.jetbrains.com/issue/KT-6660). -## 5. Handling Kotlin code +## 5. Handling Kotlin Code If you need to write a plugin that processes Kotlin code, you need to add a dependency on the Kotlin plugin. Please refer to [Plugin Dependencies](/basics/plugin_structure/plugin_dependencies.md) for information on how to do that. diff --git a/tutorials/project_wizard/adding_new_steps.md b/tutorials/project_wizard/adding_new_steps.md index b583e6616..a5682040a 100644 --- a/tutorials/project_wizard/adding_new_steps.md +++ b/tutorials/project_wizard/adding_new_steps.md @@ -5,7 +5,7 @@ title: Adding New Steps to Project Wizard This tutorial shows how to add an extra step to the Project Wizard to provide additional project configuration settings. -## Pre-requirements +## Pre-Requirements Create an empty plugin project. See [Creating a Plugin Project](/tutorials/build_system.md) diff --git a/tutorials/project_wizard/module_types.md b/tutorials/project_wizard/module_types.md index 8c444dd58..5af64af70 100644 --- a/tutorials/project_wizard/module_types.md +++ b/tutorials/project_wizard/module_types.md @@ -6,7 +6,7 @@ title: Supporting Module Types *IntelliJ Platform* provides a set of standard module types. However, an application might need a module of a type that isn't supported yet. This tutorial shows how to register a new module type and link it to the project creation procedure and the UI. -## Pre-requirements +## Pre-Requirements Create an empty plugin project, see [Creating a Plugin Project](/tutorials/build_system.md). diff --git a/tutorials/run_configurations.md b/tutorials/run_configurations.md index 14a58ff65..9ac09b035 100644 --- a/tutorials/run_configurations.md +++ b/tutorials/run_configurations.md @@ -10,13 +10,13 @@ To get familiar with the concept of a Run Configuration refer section of [IntelliJ IDEA Web Help](https://www.jetbrains.com/idea/help/intellij-idea.html) -## Pre-requirements +## Pre-Requirements Create an empty plugin project. See [Creating a Plugin Project](/basics/getting_started/creating_plugin_project.md). -## 1. Register a new ConfigurationType +## 1. Register a New ConfigurationType Add new *configurationType* extension to the [plugin.xml](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/run_configuration/src/main/resources/META-INF/plugin.xml) diff --git a/tutorials/tree_structure_view.md b/tutorials/tree_structure_view.md index c6622f246..8e4ec9036 100644 --- a/tutorials/tree_structure_view.md +++ b/tutorials/tree_structure_view.md @@ -11,7 +11,7 @@ of Series of step below show how to filter out and keep visible only text files and directories in the Project View Panel. -## Pre-requirements +## Pre-Requirements Create an empty plugin project. See @@ -48,7 +48,7 @@ public class TextOnlyTreeStructureProvider implements TreeStructureProvider { } ``` -## 3. Override modify() method +## 3. Override modify() Method To implement Tree Structure nodes filtering logic, override `modify()` method. The example below shows how to filter out all the Project View nodes except those which correspond to text files and directories. diff --git a/user_interface_components/kotlin_ui_dsl.md b/user_interface_components/kotlin_ui_dsl.md index d2349da13..adeb35d23 100644 --- a/user_interface_components/kotlin_ui_dsl.md +++ b/user_interface_components/kotlin_ui_dsl.md @@ -224,7 +224,7 @@ checkBox(message("checkbox.smart.tab.reuse"), comment = message("checkbox.smart.tab.reuse.inline.help")) ``` -## Integrating panels with property bindings +## Integrating Panels with Property Bindings A panel returned by the `panel` method is an instance of [`DialogPanel`](upsource:///platform/platform-api/src/com/intellij/openapi/ui/DialogPanel.kt). This base class supports the standard `apply`, `reset`, and `isModified` methods. @@ -288,6 +288,6 @@ val panel = panel { ## FAQ -### One cell is minimum, second one is maximum +### One Cell Is Minimum, Second One Is Maximum Set `CCFlags.growX` and `CCFlags.pushX` for some component in the second cell.