add syntax errors and controlling highlighting sections

ijs.tree

@@ -196,13 +196,15 @@
             <toc-element id="code_intentions.md" toc-title="Intentions"/>
         </toc-element>
         <toc-element id="analyzing.md" toc-title="Analysing">
-            <toc-element toc-title="Annotator"/>
+            <toc-element id="syntax_errors.md"/>
+            <toc-element toc-title="Annotators"/>
             <toc-element id="code_inspections.md" toc-title="Inspections">
                 <toc-element toc-title="Profiles"/>
                 <toc-element toc-title="Scopes"/>
                 <toc-element toc-title="Suppressing Highlights"/>
                 <toc-element toc-title="Structural Search"/>
             </toc-element>
+            <toc-element id="controlling_highlighting.md"/>
         </toc-element>
         <toc-element toc-title="Refactoring"/>
         <toc-element id="project_view.md">

topics/tutorials/controlling_highlighting.md

@@ -0,0 +1,31 @@
+[//]: # (title: Controlling Highlighting)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+
+The results of analyzing code by several mechanisms provided by the IntelliJ Platform ([Syntax errors](syntax_errors.md), Annotators, [Inspections](code_inspections.md)) are converted to highlighting information used to highlight the code in the editor. However, in some contexts, provided highlighting information is invalid or unnecessary.
+
+Consider a tool that allows changing Java language's syntax by implicitly generating getters and setters for annotated fields during the build, so they can be omitted in class implementation:
+
+```java
+class Person {
+    @GetterSetter
+    private int age;
+}
+
+// usage:
+person.setAge(47); // valid at runtime
+```
+
+Java support in IntelliJ IDEA would report such a setter usage as an unresolved code symbol. Error annotation would be valid from the Java language point of view but invalid in a project using such a tool.
+
+Another case where highlighting code issues is unnecessary is old file revisions from VCS. For example, the old version of a file could be created in a different project context, with other libraries configured. If the old file version used the library that is not used by the project currently, it would cause reporting false-positive code issues.
+
+The IntelliJ Platform exposes the extension point allowing a plugin to decide which highlighting information will be visible in the editor. To do that a plugin has to provide implementation of [`HighlightInfoFilter`](upsource:///platform/analysis-impl/src/com/intellij/codeInsight/daemon/impl/HighlightInfoFilter.java) and register it in the `com.intellij.daemon.highlightInfoFilter` EP.
+The `HighlightInfoFilter` class contains a single method `accept()` which should return true if a given `HighlightInfo` should be visible in the editor and return false to ignore it.
+
+**Examples:**
+- [`DebuggerHighlightFilter`](upsource:///java/debugger/impl/src/com/intellij/debugger/engine/evaluation/DebuggerHighlightFilter.java)  disabling reporting unhandled exceptions in debugger code editor
+- [`LombokHighlightErrorFilter`](upsource:///plugins/lombok/src/main/java/de/plushnikov/intellij/plugin/extension/LombokHighlightErrorFilter.java) disabling false-positive error reports in a project using Lombok
+
+**See also:**
+- [Controlling Syntax Errors Highlighting](syntax_errors.md#controlling-syntax-errors-highlighting)

topics/tutorials/syntax_errors.md

@@ -0,0 +1,28 @@
+[//]: # (title: Syntax Errors)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+
+The IntelliJ Platform provides a mechanism for analyzing the PSI tree and highlighting syntax errors out of the box.
+
+While the PSI tree for the code is being built, a parser tries to consume tokens according to language grammar. When it encounters a syntax error, like an unexpected token, a [`PsiErrorElement`](upsource:///platform/core-api/src/com/intellij/psi/PsiErrorElement.java) is created and added to the PSI tree with an appropriate error description.
+In the code analysis daemon, the IntelliJ Platform visits every PSI element in the tree, and when a `PsiErrorElement` is encountered, information about it is collected and used while highlighting the code in the editor.
+
+## Controlling Syntax Errors Highlighting
+
+In some cases highlighting syntax errors is insufficient or even unnecessary:
+- An error can be presented to the user in an easier-to-understand way.
+- The actual error cause is in a different location in the code, which is not easily visible when looking at the syntax error.
+- An error can be safely ignored in a given context, e.g. incomplete code fragment injected in a Markdown code block.
+- A syntax error is not critical and can be considered as a warning or even information.
+
+The IntelliJ Platform allows plugins to disable highlighting particular syntax errors. These errors can be optionally handled by additional Annotators or [Inspections](code_inspections.md) if needed.
+
+To control which `PsiErrorElement`s should be reported and which can be ignored, a plugin has to provide implementation of [`HighlightErrorFilter`](upsource:///platform/analysis-api/src/com/intellij/codeInsight/highlighting/HighlightErrorFilter.java) and register it in the `com.intellij.highlightErrorFilter` extension point.
+The `HighlightErrorFilter` class contains a single abstract method `shouldHighlightErrorElement()` which should return false if a given `PsiErrorElement` should not be highlighted in the editor.
+
+**Examples:**
+- [`HtmlClosingTagErrorFilter`](upsource:///xml/xml-analysis-impl/src/com/intellij/codeInsight/highlighting/HtmlClosingTagErrorFilter.java) ignoring unmatched closing tag in HTML files
+- [`CodeFenceHighlightErrorFilter`](upsource:///plugins/markdown/src/org/intellij/plugins/markdown/injection/MarkdownCodeFenceErrorHighlightingIntention.kt) ignoring all syntax errors in a code injected into a Markdown code blocks
+
+**See also:**
+- [Controlling Highlighting](controlling_highlighting.md)