syntax_highlighting_and_error_highlighting.md: Order of Running Highlighting

topics/appendix/api_notable/api_notable_list_2024.md

@@ -18,6 +18,9 @@ _Early Access Program_ (EAP) releases of upcoming versions are available [here](
 
 ### IntelliJ Platform 2024.1
 
+Running highlighting
+: Highlighting is now performed more efficiently, please refer to [](syntax_highlighting_and_error_highlighting.md#order-of-running-highlighting).
+
 Status bar widget for LSP servers
 : Language plugins using LSP can now provide their status for [](language_server_protocol.md#status-bar-integration).
 

topics/intro/content_updates.md

@@ -19,7 +19,9 @@ Kotlin Coroutines
 : Add [](kotlin_coroutines.md) describing how to write asynchronous code in an imperative style.
 
 Minor Changes and Additions
-: Add [documentation](plugin_extension_points.md#error-handling) on how to handle errors and deprecations in extensions.
+:
+- Add [documentation](plugin_extension_points.md#error-handling) on how to handle errors and deprecations in extensions.
+- Note changes in how highlighting is now [performed more efficiently](syntax_highlighting_and_error_highlighting.md#order-of-running-highlighting) in 2024.1.
 
 ### February
 {#february-24}

topics/reference_guide/custom_language_support/code_inspections_and_intentions.md

@@ -1,6 +1,6 @@
-# Code Inspections and Intentions
+<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
-<!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
+# Code Inspections and Intentions
 
 <link-summary>Introduction to analysing the code and providing quick fixes for the found issues.</link-summary>
 
@@ -31,6 +31,8 @@ See [Inspections](https://jetbrains.design/intellij/text/inspections/) topic in
 - [Code Inspections Tutorial](code_inspections.md)
 - A [simple inspection](%gh-ic%/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/codeInspection/TrailingSpacesInPropertyInspection.java) for [Properties language plugin](%gh-ic%/plugins/properties)
 
+> Please also note important change in 2024.1, refer to [](syntax_highlighting_and_error_highlighting.md#order-of-running-highlighting).
+
 #### Inspections Performance
 
 A [custom language plugin](custom_language_support.md) providing many inspections (>100) can register the default [`PsiElementVisitor`](%gh-ic%/platform/core-api/src/com/intellij/psi/PsiElementVisitor.java)

topics/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md

@@ -165,3 +165,37 @@ Existing highlighting can be suppressed programmatically in certain contexts, se
 
 To force re-highlighting all open or specific file(s) (e.g., after changing plugin specific settings), use
 [`DaemonCodeAnalyzer.restart()`](%gh-ic%/platform/analysis-api/src/com/intellij/codeInsight/daemon/DaemonCodeAnalyzer.java).
+
+## Order of Running Highlighting
+
+Since 2024.1, [inspections](code_inspections_and_intentions.md) and [annotators](#annotator) do not run sequentially on each `PsiElement` anymore.
+Instead, they're run in parallel on all relevant PSI independently with the following consequences.
+
+**Independent Annotators**
+
+[Annotators](#annotator) are run independent of each other: if an annotator found an error, it no longer stops annotating the `PsiElement`'s parents.
+Effectively, there is "more" highlighting now.
+
+**Highlight Range**
+
+Producing highlights must be done as close as possible for the relevant `PsiElement`.
+For example, instead of
+
+```text
+annotate(PsiFile) {
+  <<highlight all relevant identifiers>>
+}
+```
+
+this approach should be used:
+
+```text
+annotate(PsiIdentifier) {
+  <<highlight this identifier if it's relevant>>
+}
+```
+
+The latter version:
+- performs faster highlighting — it doesn’t have to wait until all other identifiers are visited
+- removes outdated highlights faster — right after the identifier was visited and the annotator didn't produce a highlighting anymore
+