From a2a2ac9026901e17c61852f2b00a8527be7f18b7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yann=20C=C3=A9bron?= <yann.cebron@jetbrains.com>
Date: Wed, 13 Mar 2024 13:53:19 +0100
Subject: [PATCH] plugin_extension_points.md: error handling

---
 .../plugin_extension_points.md                | 21 +++++++++++++++----
 topics/intro/content_updates.md               |  6 ++++++
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/topics/basics/plugin_structure/plugin_extension_points.md b/topics/basics/plugin_structure/plugin_extension_points.md
index b6131c14c..e5731ba81 100644
--- a/topics/basics/plugin_structure/plugin_extension_points.md
+++ b/topics/basics/plugin_structure/plugin_extension_points.md
@@ -48,9 +48,9 @@ Its fully qualified name required in [Using Extension Points](#using-extension-p
 
 The `beanClass` attribute sets a bean class that specifies one or several properties annotated with the [`@Attribute`](%gh-ic%/platform/util/src/com/intellij/util/xmlb/annotations/Attribute.java) annotation.
 Note that bean classes do not follow the JavaBean standard.
-Implement [`PluginAware`](%gh-ic%/platform/extensions/src/com/intellij/openapi/extensions/PluginAware.java) to obtain information about the plugin providing the actual extension.
+Implement [`PluginAware`](%gh-ic%/platform/extensions/src/com/intellij/openapi/extensions/PluginAware.java) to obtain information about the plugin providing the actual extension (see [](#error-handling)).
 
-The `interface` attribute sets an interface the plugin that contributes to the extension point must implement.
+Alternatively, the `interface` attribute sets an interface the plugin that contributes to the extension point must then implement.
 
 The `area` attribute determines the scope in which the extension will be instantiated.
 As extensions should be stateless, it is **not** recommended to use non-default.
@@ -79,7 +79,7 @@ To clarify this, consider the following sample `MyBeanClass` bean class used in
 <path>myPlugin/src/com/myplugin/MyBeanClass.java</path>
 
 ```java
-public class MyBeanClass extends AbstractExtensionPointBean {
+public final class MyBeanClass extends AbstractExtensionPointBean {
 
   @Attribute("key")
   public String key;
@@ -132,7 +132,8 @@ To refer to all registered extension instances at runtime, declare an [`Extensio
 <path>myPlugin/src/com/myplugin/MyExtensionUsingService.java</path>
 
 ```java
-public class MyExtensionUsingService {
+@Service
+public final class MyExtensionUsingService {
 
   private static final ExtensionPointName<MyBeanClass> EP_NAME =
       ExtensionPointName.create("my.plugin.myExtensionPoint1");
@@ -151,6 +152,18 @@ public class MyExtensionUsingService {
 A gutter icon for the `ExtensionPointName` declaration allows navigating to the corresponding [`<extensionPoint>`](plugin_configuration_file.md#idea-plugin__extensionPoints__extensionPoint) declaration in <path>plugin.xml</path>.
 Code insight is available for the extension point name String literal (2022.3).
 
+### Error Handling
+
+When processing extension implementations or registrations, there might be errors, compatibility and configuration issues.
+Use [`PluginException`](%gh-ic%/platform/core-api/src/com/intellij/diagnostic/PluginException.java) to log and correctly attribute the causing plugin for
+[builtin error reporting](ide_infrastructure.md#error-reporting).
+
+To report use of deprecated API, use `PluginException.reportDeprecatedUsage()` methods.
+
+**Examples:**
+- [`CompositeFoldingBuilder.assertSameFile()`](%gh-ic%/platform/core-api/src/com/intellij/lang/folding/CompositeFoldingBuilder.java)
+- [`InspectionProfileEntry.getDisplayName()`](%gh-ic%/platform/analysis-api/src/com/intellij/codeInspection/InspectionProfileEntry.java)
+
 ## Dynamic Extension Points
 
 To support [Dynamic Plugins](dynamic_plugins.md) (2020.1 and later), an extension point must adhere to specific usage rules:
diff --git a/topics/intro/content_updates.md b/topics/intro/content_updates.md
index 487ccbfef..15a31c028 100644
--- a/topics/intro/content_updates.md
+++ b/topics/intro/content_updates.md
@@ -12,6 +12,12 @@ See [GitHub Changelog](https://github.com/JetBrains/intellij-sdk-docs/commits/ma
 
 ## 2024
 
+### March
+{#march-24}
+
+Minor Changes and Additions
+: Add [documentation](plugin_extension_points.md#error-handling) on how to handle errors and deprecations in extensions.
+
 ### February
 {#february-24}