From 04a48491c7b38cae55750f17fc00d30e7bfb3941 Mon Sep 17 00:00:00 2001 From: Karol Lewandowski Date: Thu, 9 Jan 2025 15:45:21 +0100 Subject: [PATCH] Move base extension attributes to plugin_configuration_file.md --- .../generate_descriptor_pages.main.kts | 15 +++- .../plugin_configuration_file.md | 82 +++++++++++++++---- .../plugin_structure/plugin_extensions.md | 18 +--- 3 files changed, 82 insertions(+), 33 deletions(-) diff --git a/.github/scripts/generate_descriptor_pages.main.kts b/.github/scripts/generate_descriptor_pages.main.kts index ce5bdacaf..dcb625c3c 100755 --- a/.github/scripts/generate_descriptor_pages.main.kts +++ b/.github/scripts/generate_descriptor_pages.main.kts @@ -1,6 +1,6 @@ #!/usr/bin/env kotlin -// Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. +// Copyright 2000-2025 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. /** * Generates the elements content for pages defined in [descriptors]. @@ -115,8 +115,9 @@ fun StringBuilder.appendElementsHierarchy(elements: List, level: Int, p } fun StringBuilder.appendHierarchyLink(element: Element, level: Int, elementSectionLink: String) { + val elementName = if (element.isWildcard()) (element.descriptiveName ?: "*") else "`<${element.name}>`" appendLine( - """${" ".repeat(level)}- [`<${element.name}>`](#$elementSectionLink)${if (element.deprecatedSince != null) " ![Deprecated][deprecated]" else ""}""" + """${" ".repeat(level)}- [$elementName](#$elementSectionLink)${if (element.deprecatedSince != null) " ![Deprecated][deprecated]" else ""}""" ) } @@ -176,7 +177,8 @@ fun StringBuilder.appendSectionHeader( elementSectionLink: String, addDeprecationLabel: Boolean ) { - appendLine("\n#${"#".repeat(level)} `${element.name}`") + val title = if (element.isWildcard()) (element.descriptiveName ?: "*") else "`${element.name}`" + appendLine("\n#${"#".repeat(level)} $title") val attributes = StringBuilder() attributes.append("{") attributes.append("#$elementSectionLink") @@ -452,6 +454,7 @@ data class ElementWrapper( data class Element( var name: String? = null, + var descriptiveName: String? = null, var sdkDocsFixedPath: List = emptyList(), var since: String? = null, var until: String? = null, @@ -467,7 +470,11 @@ data class Element( var requirement: Requirement? = null, var defaultValue: String? = null, var examples: List = emptyList(), -) +) { + fun isWildcard(): Boolean { + return name == "*" + } +} // allows for referencing attributes by anchors in YAML data class AttributeWrapper( diff --git a/topics/basics/plugin_structure/plugin_configuration_file.md b/topics/basics/plugin_structure/plugin_configuration_file.md index 46112513c..d092c330b 100644 --- a/topics/basics/plugin_structure/plugin_configuration_file.md +++ b/topics/basics/plugin_structure/plugin_configuration_file.md @@ -52,6 +52,7 @@ Deprecated elements are omitted in the list below. - [``](#idea-plugin__depends) - [``](#idea-plugin__incompatible-with) - [``](#idea-plugin__extensions) + - [An Extension](#idea-plugin__extensions__*) - [``](#idea-plugin__extensionPoints) - [``](#idea-plugin__extensionPoints__extensionPoint) - [``](#idea-plugin__extensionPoints__extensionPoint__with) @@ -537,28 +538,79 @@ Attributes Children : -The children elements are registrations of the extension points defined by -[``](#idea-plugin__extensionPoints__extensionPoint) elements. Extension elements names follow the EPs names -defined by `name` +The children elements are registrations of instances +of [extension points](#idea-plugin__extensionPoints__extensionPoint) provided by the IntelliJ Platform or plugins. +
+An extension element name is defined by its extension point via +`name` or `qualifiedName` attributes. +
+An extension element attributes depend on the extension point implementation, but all extensions support basic attributes: +`id`, `order`, +and `os`. Examples : - Extensions' declaration with a default namespace: -```xml - - - -``` + ```xml + + + + ``` - Extensions' declaration using the fully qualified extension name: -```xml - - - -``` + ```xml + + + + ``` + +#### An Extension +{#idea-plugin__extensions__*} + +An extension instance registered under [``](#idea-plugin__extensions). + +Listed attributes are basic attributes available for all extensions. +The list of actual attributes can be longer depending on the extension point implementation. + + + +{type="narrow"} +Attributes +: +- `id` _(optional)_
+ Unique extension identifier. + It allows for referencing an extension in the `order` attribute. +
+ To not clash with other plugins defining extensions with the same identifier, + consider prepending the identifier with a prefix related to the plugin [``](#idea-plugin__id) or + [``](#idea-plugin__name), for example, `id="com.example.myplugin.myExtension"`. +- `order` _(optional)_
+ Allows for ordering the extension relative to other instances of the same extension point. + Supported values: + - `first` - orders the extension as first. + It is not guaranteed that the extension will be the first if multiple extensions are defined as `first`. + - `last` - orders the extension as last. + It is not guaranteed that the extension will be the last if multiple extensions are defined as `last`. + - `before extension_id` - orders the extension before an extension with + the given `id` + - `after extension_id` - orders the extension after an extension with + the given `id` +
+ Values can be combined, for example, `order="after extensionY, before extensionX"`. +- `os` _(optional)_
+ + Allows restricting an extension to a given OS. + Supported values: + - `freebsd` + - `linux` + - `mac` + - `unix` + - `windows` + + For example, `os="windows"` registers the extension on Windows only. ### `extensionPoints` {#idea-plugin__extensionPoints} diff --git a/topics/basics/plugin_structure/plugin_extensions.md b/topics/basics/plugin_structure/plugin_extensions.md index 33f2bd9aa..1aa9c3032 100644 --- a/topics/basics/plugin_structure/plugin_extensions.md +++ b/topics/basics/plugin_structure/plugin_extensions.md @@ -41,7 +41,8 @@ See [](explore_api.md) for more information and strategies. * If the extension point was declared using the `beanClass` attribute, set all properties annotated with the [`@Attribute`](%gh-ic%/platform/util/src/com/intellij/util/xmlb/annotations/Attribute.java) and [`Tag`](%gh-ic%/platform/util/src/com/intellij/util/xmlb/annotations/Tag.java) annotations in the specified bean class. See the [](plugin_extension_points.md#declaring-extension-points) section for details. -4. Implement the extension API as required (see [](#implementing-extension)). +4. In addition to attributes defined by the extension point, the extension element can specify basic attributes (see the attributes list in [](plugin_configuration_file.md#idea-plugin__extensions__*) section). +5. Implement the extension API as required (see [](#implementing-extension)). @@ -87,21 +88,10 @@ When using [Kotlin](using_kotlin.md): - Do not use `companion object` to avoid excessive classloading/initialization when the extension class is loaded. Use top-level declarations or objects instead. [More details](using_kotlin.md#companion-object-extensions) +> If an extension instance needs to "opt out" in certain scenarios, it can throw [`ExtensionNotApplicableException`](%gh-ic%/platform/extensions/src/com/intellij/openapi/extensions/ExtensionNotApplicableException.java) in its constructor. + -### Extension Default Properties - -`id` -: Unique ID. Consider prepending ID with the prefix related to the plugin name or ID to not clash with other plugins defining extensions with the same ID, for example, `com.example.myplugin.myExtension`. - -`order` -: Allows ordering all defined extensions using `first`, `last` or `before|after [id]` respectively. - -`os` -: Allows restricting an extension to a given OS, for example, `os="windows"` registers the extension on Windows only - -If an extension instance needs to "opt out" in certain scenarios, it can throw [`ExtensionNotApplicableException`](%gh-ic%/platform/extensions/src/com/intellij/openapi/extensions/ExtensionNotApplicableException.java) in its constructor. - ### Extension Properties Code Insight Several tooling features are available to help configure bean class extension points in plugin.xml.