Move base extension attributes to plugin_configuration_file.md

.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<Element>, 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<String> = 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<String> = emptyList(),
-)
+) {
+  fun isWildcard(): Boolean {
+    return name == "*"
+  }
+}
 
 // allows for referencing attributes by anchors in YAML
 data class AttributeWrapper(

topics/basics/plugin_structure/plugin_configuration_file.md

@@ -52,6 +52,7 @@ Deprecated elements are omitted in the list below.
   - [`<depends>`](#idea-plugin__depends)
   - [`<incompatible-with>`](#idea-plugin__incompatible-with)
   - [`<extensions>`](#idea-plugin__extensions)
+    - [An Extension](#idea-plugin__extensions__*)
   - [`<extensionPoints>`](#idea-plugin__extensionPoints)
     - [`<extensionPoint>`](#idea-plugin__extensionPoints__extensionPoint)
       - [`<with>`](#idea-plugin__extensionPoints__extensionPoint__with)
@@ -537,28 +538,79 @@ Attributes
 
 Children
 :
-The children elements are registrations of the extension points defined by
-[`<extensionPoint>`](#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.
+<br/>
+An extension element name is defined by its extension point via
+`name`
 or `qualifiedName` attributes.
+<br/>
+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
-<extensions defaultExtensionNs="com.intellij">
+    ```xml
+    <extensions defaultExtensionNs="com.intellij">
       <applicationService
           serviceImplementation="com.example.Service"/>
-</extensions>
-```
+    </extensions>
+    ```
 - Extensions' declaration using the fully qualified extension name:
-```xml
-<extensions>
+    ```xml
+    <extensions>
       <com.example.vcs.myExtension
           implementation="com.example.MyExtension"/>
-</extensions>
-```
+    </extensions>
+    ```
+
+#### An Extension
+{#idea-plugin__extensions__*}
+
+An extension instance registered under [`<extensions>`](#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)_<br/>
+  Unique extension identifier.
+  It allows for referencing an extension in the `order` attribute.
+  <br/>
+  To not clash with other plugins defining extensions with the same identifier,
+  consider prepending the identifier with a prefix related to the plugin [`<id>`](#idea-plugin__id) or 
+  [`<name>`](#idea-plugin__name), for example, `id="com.example.myplugin.myExtension"`.
+- `order` _(optional)_<br/>
+  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`
+  <br/>
+  Values can be combined, for example, `order="after extensionY, before extensionX"`.
+- `os` _(optional)_<br/>
+
+    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}

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)).
 
 </procedure>
 
@@ -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.
+
 </procedure>
 
-### 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 <path>plugin.xml</path>.