plugin_configuration_file.md: content update

x130379789 · Oct 19, 2021 · 96c58ee · 96c58ee
1 parent 1c5dd20
commit 96c58ee
Show file tree

Hide file tree

Showing 23 changed files with 100 additions and 96 deletions.
diff --git a/code_samples/action_basics/src/main/resources/META-INF/plugin.xml b/code_samples/action_basics/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/comparing_references_inspection/src/main/resources/META-INF/plugin.xml b/code_samples/comparing_references_inspection/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/conditional_operator_intention/src/main/resources/META-INF/plugin.xml b/code_samples/conditional_operator_intention/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/editor_basics/src/main/resources/META-INF/plugin.xml b/code_samples/editor_basics/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/facet_basics/src/main/resources/META-INF/plugin.xml b/code_samples/facet_basics/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/framework_basics/src/main/resources/META-INF/plugin.xml b/code_samples/framework_basics/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/inspection_basics/src/main/resources/META-INF/plugin.xml b/code_samples/inspection_basics/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/kotlin_demo/src/main/resources/META-INF/plugin.xml b/code_samples/kotlin_demo/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/live_templates/src/main/resources/META-INF/plugin.xml b/code_samples/live_templates/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/max_opened_projects/src/main/resources/META-INF/plugin.xml b/code_samples/max_opened_projects/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/module/src/main/resources/META-INF/plugin.xml b/code_samples/module/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/product_specific/pycharm_basics/src/main/resources/META-INF/plugin.xml b/code_samples/product_specific/pycharm_basics/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/project_model/src/main/resources/META-INF/plugin.xml b/code_samples/project_model/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/project_view_pane/src/main/resources/META-INF/plugin.xml b/code_samples/project_view_pane/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/project_wizard/src/main/resources/META-INF/plugin.xml b/code_samples/project_wizard/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/psi_demo/src/main/resources/META-INF/plugin.xml b/code_samples/psi_demo/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/run_configuration/src/main/resources/META-INF/plugin.xml b/code_samples/run_configuration/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/settings/src/main/resources/META-INF/plugin.xml b/code_samples/settings/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/simple_language_plugin/src/main/resources/META-INF/plugin.xml b/code_samples/simple_language_plugin/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/theme_basics/resources/META-INF/plugin.xml b/code_samples/theme_basics/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/tool_window/src/main/resources/META-INF/plugin.xml b/code_samples/tool_window/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/code_samples/tree_structure_provider/src/main/resources/META-INF/plugin.xml b/code_samples/tree_structure_provider/src/main/resources/META-INF/plugin.xml
@@ -1,4 +1,5 @@
 <!-- Copyright 2000-2020 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. -->
+<!-- Plugin Configuration File. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-configuration-file.html -->
 
 <idea-plugin>
 

diff --git a/topics/basics/plugin_structure/plugin_configuration_file.md b/topics/basics/plugin_structure/plugin_configuration_file.md
@@ -13,71 +13,93 @@ Allowed HTML elements include text formatting, paragraphs, and lists.
 When using Gradle, a number of metadata elements will be provided at build time by [`patchPluginXml` task](gradle_guide.md#patching-the-plugin-configuration-file).
 
 ```xml
-<!-- `url` specifies the URL of the plugin homepage (can be opened from "Plugins" settings dialog) -->
-<idea-plugin url="https://www.jetbrains.com/idea">
+<!-- An optional `url` attribute specifies the link to the plugin homepage. Displayed on the Plugin Page. -->
+<idea-plugin url="https://plugins.jetbrains.com">
 
-  <!-- Plugin name. It should be short and descriptive and in Title Case.
-       Displayed in the "Plugins" settings dialog and the plugin repository Web interface. -->
-  <name>Vss Integration</name>
-
-  <!-- Unique identifier of the plugin. It should be FQN.
-       It cannot be changed between the plugin versions.
+  <!-- Unique identifier of the plugin. It should be FQN. It cannot be changed between the plugin versions.
        If not specified, <name> will be used (not recommended). -->
-  <id>com.jetbrains.vssintegration</id>
-
-  <!-- Description of the plugin.
-       Should be short and to the point.
-       Start the description with a verb in a present simple form such as
-       "integrates", "synchronizes", "adds support for" or "lets you view".
-       Don't use marketing adjectives like "simple", "lightweight", or "professional".
-       Don't repeat the name of the plugin.
-       For plugins that add language/platform/framework support, the description MUST specify
-       the version of the corresponding language/platform/framework.
-       Don't mention the IDE compatibility. E.g., don't say "Adds support to IntelliJ IDEA for..."
-       Displayed in the "Plugins" settings dialog and the plugin repository Web interface.
-       Simple HTML elements can be included between <![CDATA[  ]]> tags.  -->
-  <description>Integrates Volume Snapshot Service W10</description>
-
-  <!-- Description of changes in the latest version of the plugin.
-       Displayed in the "Plugins" settings dialog and the plugin repository Web interface.
-       Simple HTML elements can be included between <![CDATA[  ]]> tags.  -->
-  <change-notes>Initial release of the plugin.</change-notes>
+  <id>org.jetbrains.plugins.template</id>
 
-  <!-- Plugin version
-       Recommended format is BRANCH.BUILD.FIX (MAJOR.MINOR.FIX)
-       Displayed in the "Plugins" settings dialog and the plugin repository Web interface.  -->
-  <version>1.0.0</version>
+  <!-- Public plugin name should be written in Title Case. Guidelines: https://plugins.jetbrains.com/docs/marketplace/plugin-overview-page.html#plugin-name -->
+  <name>Plugin Template</name>
 
-  <!-- The vendor of the plugin.
-       The optional "url" attribute specifies the URL of the vendor homepage.
-       The optional "email" attribute specifies the e-mail address of the vendor.
+  <!-- Plugin version. It is recommended to use the SemVer approach: https://semver.org
        Displayed in the "Plugins" settings dialog and the plugin repository Web interface. -->
-  <vendor url="https://www.company.com" email="[email protected]">A Company Inc.</vendor>
+  <version>1.0.0</version>
+
+  <!-- A displayed Vendor name or Organization ID (if you have one created. The optional `URL` attribute specifies
+       the link to the vendor’s homepage.The optional `email` attribute specifies the vendor’s e-mail address.
+       Displayed on the Plugins Page. -->
+  <vendor url="https://plugins.jetbrains.com" email="[email protected]">JetBrains</vendor>
+
+  <!-- IMPORTANT: This tag should not be used in case of free plugins.
+       If you decide to make your plugin paid, you will need to define the parameters in the <product-descriptor> tag.
+       You can also enable free functionality in a paid plugin. Learn more in a guide to selling plugin:
+       https://plugins.jetbrains.com/build-and-market -->
+  <product-descriptor code="PLUGINTEMPLATE" release-date="20210901" release-version="20211" optional="true"/>
 
-  <!-- Mandatory dependencies on plugins or modules.
-       The FQN module names in <depends> elements are used to determine IDE compatibility for the plugin.
-       Include at least the module shown below to indicate compatibility with IntelliJ Platform-based products.
-       Also, include dependencies on other plugins as needed.
-       See "Compatibility with Multiple Products" and "Plugin Dependencies" for more information.  -->
+  <!-- Minimum and maximum build version of IDE compatible with the plugin. -->
+  <idea-version since-build="193" until-build="193.*"/>
+
+  <!-- Description of the plugin displayed on the Plugin Page and IDE Plugin Manager.
+       Simple HTML elements ( text formatting, paragraphs, and lists) can be added inside of <![CDATA[ ]]> tag.
+       Guidelines: https://plugins.jetbrains.com/docs/marketplace/plugin-overview-page.html#plugin-description -->
+  <description>
+  <![CDATA[
+    Provides a boilerplate template for easier plugin creation. <br/>
+    Speed up the setup phase of plugin development for both new and experienced developers.
+  ]]>
+  </description>
+
+  <!-- Short summary of new features and bugfixes in the latest plugin version.
+       Displayed on the Plugin Page and IDE Plugin Manager. Simple HTML elements can be included between <![CDATA[  ]]> tags. -->
+  <change-notes>Initial release of the plugin.</change-notes>
+
+  <!-- Product and plugin compatibility requirements. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-compatibility.html -->
   <depends>com.intellij.modules.platform</depends>
   <depends>com.third.party.plugin</depends>
 
-  <!-- Optional dependency on another plugin.
-       If the plugin with the "com.MySecondPlugin" ID is installed, the contents of mysecondplugin.xml
-       (the format of this file conforms to the format of plugin.xml) will be loaded. -->
+  <!-- Optional dependency on another plugin. If the plugin with the "com.MySecondPlugin" ID is installed,
+       the contents of mysecondplugin.xml (the format of this file conforms to the format of plugin.xml) will be loaded. -->
   <depends optional="true" config-file="mysecondplugin.xml">com.MySecondPlugin</depends>
 
-  <!-- Minimum and maximum build of IDE compatible with the plugin -->
-  <idea-version since-build="193" until-build="193.*"/>
-
-  <!-- Resource bundle (/messages/MyPluginBundle.properties) to be used
-       with `key` attributes in extension points and implicit keys like
-       `action.[ActionID].text|description` -->
+  <!-- Resource bundle (/messages/MyPluginBundle.properties) to be used with `key` attributes in extension points
+       and implicit keys like `action.[ActionID].text|description`. -->
   <resource-bundle>messages.MyPluginBundle</resource-bundle>
 
-  <!-- Plugin's application components / DEPRECATED - do not use in new plugins
-       See https://plugins.jetbrains.com/docs/intellij/plugin-components.html for migration steps
-  -->
+  <!-- Extension points defined by the plugin. Extension points are registered by a plugin so that other plugins can provide
+       this plugin with certain data. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-extension-points.html -->
+  <extensionPoints>
+    <extensionPoint name="testExtensionPoint" beanClass="com.foo.impl.MyExtensionBean"/>
+    <applicationService serviceImplementation="com.foo.impl.MyApplicationService"/>
+    <projectService serviceImplementation="com.foo.impl.MyProjectService"/>
+  </extensionPoints>
+
+  <!-- Application-level listeners, see: https://plugins.jetbrains.com/docs/intellij/plugin-listeners.html#defining-application-level-listeners -->
+  <applicationListeners>
+    <listener class="com.foo.impl.MyListener" topic="com.intellij.openapi.vfs.newvfs.BulkFileListener"/>
+  </applicationListeners>
+
+  <!-- Project-level listeners, see: https://plugins.jetbrains.com/docs/intellij/plugin-listeners.html#defining-project-level-listeners -->
+  <projectListeners>
+    <listener class="com.foo.impl.MyToolwindowListener" topic="com.intellij.openapi.wm.ex.ToolWindowManagerListener"/>
+  </projectListeners>
+
+  <!-- Actions, see: https://plugins.jetbrains.com/docs/intellij/basic-action-system.html -->
+  <actions>
+    <action id="VssIntegration.GarbageCollection" class="com.foo.impl.CollectGarbage" text="Collect _Garbage" description="Run garbage collector">
+      <keyboard-shortcut first-keystroke="control alt G" second-keystroke="C" keymap="$default"/>
+    </action>
+  </actions>
+
+  <!-- Custom extensions declaration. Read more: https://plugins.jetbrains.com/docs/intellij/plugin-extensions.html#declaring-extensions -->
+  <extensions defaultExtensionNs="VssIntegration">
+    <myExtensionPoint implementation="com.foo.impl.MyExtensionImpl"/>
+  </extensions>
+
+
+  <!-- DEPRECATED: Plugin's application components / do not use in new plugins.
+       See https://plugins.jetbrains.com/docs/intellij/plugin-components.html for migration steps. -->
   <application-components>
     <component>
       <!-- Component's interface class -->
@@ -88,9 +110,8 @@ When using Gradle, a number of metadata elements will be provided at build time
     </component>
   </application-components>
 
-  <!-- Plugin's project components / DEPRECATED - do not use in new plugins
-       See https://plugins.jetbrains.com/docs/intellij/plugin-components.html for migration steps
-  -->
+  <!-- DEPRECATED: Plugin's project components - do not use in new plugins.
+       See https://plugins.jetbrains.com/docs/intellij/plugin-components.html for migration steps. -->
   <project-components>
     <component>
       <!-- Interface and implementation classes are the same -->
@@ -108,51 +129,12 @@ When using Gradle, a number of metadata elements will be provided at build time
     </component>
   </project-components>
 
-  <!-- Plugin's module components / DEPRECATED - do not use in new plugins
-       See https://plugins.jetbrains.com/docs/intellij/plugin-components.html for migration steps
-  -->
+  <!-- DEPRECATED: Plugin's module components - do not use in new plugins.
+       See https://plugins.jetbrains.com/docs/intellij/plugin-components.html for migration steps. -->
   <module-components>
     <component>
       <implementation-class>com.foo.Component3</implementation-class>
     </component>
   </module-components>
-
-  <!-- Actions -->
-  <actions>
-    <action id="VssIntegration.GarbageCollection" class="com.foo.impl.CollectGarbage" text="Collect _Garbage" description="Run garbage collector">
-      <keyboard-shortcut first-keystroke="control alt G" second-keystroke="C" keymap="$default"/>
-    </action>
-  </actions>
-
-  <!-- Extension points defined by the plugin.
-       Extension points are registered by a plugin so that other
-       plugins can provide this plugin with certain data.
-  -->
-  <extensionPoints>
-    <extensionPoint name="testExtensionPoint" beanClass="com.foo.impl.MyExtensionBean"/>
-  </extensionPoints>
-
-  <!-- Extensions which the plugin adds to extension points
-       defined by the IntelliJ Platform or by other plugins.
-       The "defaultExtensionNs" attribute must be set to the
-       ID of the plugin defining the extension point, or to
-       "com.intellij" if the extension point is defined by the
-       IntelliJ Platform. The name of the tag within the <extensions>
-       tag matches the name of the extension point, and the
-       "implementation" class specifies the name of the class
-       added to the extension point. -->
-  <extensions defaultExtensionNs="VssIntegration">
-    <testExtensionPoint implementation="com.foo.impl.MyExtensionImpl"/>
-  </extensions>
-
-  <!-- Application-level listeners -->
-  <applicationListeners>
-    <listener class="com.foo.impl.MyListener" topic="com.intellij.openapi.vfs.newvfs.BulkFileListener"/>
-  </applicationListeners>
-
-  <!-- Project-level listeners -->
-  <projectListeners>
-    <listener class="com.foo.impl.MyToolwindowListener" topic="com.intellij.openapi.wm.ex.ToolWindowManagerListener"/>
-  </projectListeners>
 </idea-plugin>
 ```