%gh-java-annotations% GH repo, align references/wording

topics/_shared/snippets.md

@@ -59,7 +59,7 @@ Please see [](verifying_plugin_compatibility.md) on how to use Plugin Verifier a
 
 _Early Access Program_ (EAP) releases of upcoming versions are available [here](https://eap.jetbrains.com).
 
-> Changes from API marked with `@Deprecated(forRemoval=true)` or any of [`org.jetbrains.annotations.ApiStatus`](https://github.com/JetBrains/java-annotations/blob/master/common/src/main/java/org/jetbrains/annotations/ApiStatus.java) `@Experimental`, `@ScheduledForRemoval`, or `@Internal` are not listed here, as incompatible changes are to be expected.
+> Changes from API marked with `@Deprecated(forRemoval=true)` or any of [`ApiStatus`](%gh-java-annotations%/common/src/main/java/org/jetbrains/annotations/ApiStatus.java) `@Experimental`, `@ScheduledForRemoval`, or `@Internal` are not listed here, as incompatible changes are to be expected.
 >
 > For API annotated with `ApiStatus.@Internal`/`@IntellijInternalApi`, see [](api_internal.md) for more details and replacements.
 >
@@ -110,8 +110,8 @@ See [](verifying_plugin_compatibility.md) for overview of API status.
 | ![Deprecated][deprecated]         | Deprecated API                      | Please see code documentation for replacement                                                                                                                                                                                                                                                             |
 | ![Removal][removal]               | Scheduled for Removal API           | Please see code documentation for replacement                                                                                                                                                                                                                                                             |
 | ![Obsolete][obsolete]             | Obsolete API                        | Do not use in new code, please see code documentation for replacement ([](verifying_plugin_compatibility.md#obsolete-api))                                                                                                                                                                                |
-| ![Experimental API][experimental] | Experimental API                    | Annotated with [`@ApiStatus.Experimental`](https://github.com/JetBrains/java-annotations/blob/master/common/src/main/java/org/jetbrains/annotations/ApiStatus.java), API might be altered or removed without prior notice                                                                                 |
-| ![Internal API][internal]         | Internal API                        | Annotated with [`@ApiStatus.Internal`](https://github.com/JetBrains/java-annotations/blob/master/common/src/main/java/org/jetbrains/annotations/ApiStatus.java), must not be used by 3rd party, see [](api_internal.md)                                                                                   |
+| ![Experimental API][experimental] | Experimental API                    | Annotated with [`ApiStatus.@Experimental`](%gh-java-annotations%/common/src/main/java/org/jetbrains/annotations/ApiStatus.java), API might be altered or removed without prior notice                                                                                                                     |
+| ![Internal API][internal]         | Internal API                        | Annotated with [`ApiStatus.@Internal`](%gh-java-annotations%/common/src/main/java/org/jetbrains/annotations/ApiStatus.java), must not be used by 3rd party, see [](api_internal.md)                                                                                                                       |
 | ![Project-Level][project-level]   | Project-Level Extension Point/Topic | <p>Can have [`Project`](%gh-ic%/platform/core-api/src/com/intellij/openapi/project/Project.java) as constructor parameter</p><p>Extension Point: Declared with `area="IDEA_PROJECT"`</p><p>Listener: registered in [`<projectListeners>`](plugin_configuration_file.md#idea-plugin__projectListeners)</p> |
 | ![Non-Dynamic][non-dynamic]       | Non-Dynamic Extension Point         | Installation/update of plugin requires IDE restart ([](dynamic_plugins.md))                                                                                                                                                                                                                               |
 | ![DumbAware][dumb-aware]          | `DumbAware` Extension Point         | Implementations marked with [`DumbAware`](%gh-ic%/platform/core-api/src/com/intellij/openapi/project/DumbAware.java) will be processed during [dumb mode](indexing_and_psi_stubs.md#dumb-mode)                                                                                                            |

topics/appendix/api_internal/api_internal.md

@@ -1,18 +1,18 @@
-# Internal API Migration
-
 <!-- Copyright 2000-2023 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. -->
 
-<link-summary>Lists private API annotated with ApiStatus.Internal/IntellijInternalApi and corresponding replacement.</link-summary>
+# Internal API Migration
+
+<link-summary>Lists private API annotated with ApiStatus.@Internal/@IntellijInternalApi and corresponding replacement.</link-summary>
 
-This page lists commonly used API annotated with [`org.jetbrains.annotations.ApiStatus.Internal`](https://github.com/JetBrains/java-annotations/blob/master/common/src/main/java/org/jetbrains/annotations/ApiStatus.java)
-or [`IntellijInternalApi`](%gh-ic%/platform/util/src/com/intellij/openapi/util/IntellijInternalApi.kt)
+This page lists commonly used API annotated with [`ApiStatus.@Internal`](%gh-java-annotations%/common/src/main/java/org/jetbrains/annotations/ApiStatus.java)
+or [`@IntellijInternalApi`](%gh-ic%/platform/util/src/com/intellij/openapi/util/IntellijInternalApi.kt)
 which indicates it is _private API_ and must not be used outside of IntelliJ Platform itself:
 
 > Indicates that the annotated element (class, method, field, etc.) **must not be considered as a public API**. It's made visible to allow
 > usages in other packages of the declaring library, but it **must not be used outside of that library**. Such elements
 > may be renamed, changed, or removed in future versions.
 >
-{title="ApiStatus.Internal Javadoc"}
+{title="`ApiStatus.Internal Javadoc"}
 
 Such violations are reported from [](verifying_plugin_compatibility.md#plugin-verifier) and are highlighted in the IDE using [dedicated inspection](verifying_plugin_compatibility.md#ide-support).
 
@@ -70,7 +70,7 @@ Each entry is mapped to its corresponding _Replacement_, pointing to the recomme
 
 ## Exceptions
 
-The API listed in this table is currently (or was previously) marked with `@ApiStatus.Internal`, but its status has changed in the meantime (or will change).
+The API listed in this table is currently (or was previously) marked with `ApiStatus.@Internal`, but its status has changed in the meantime (or will change).
 Therefore, any reported violations can be disregarded.
 
 | Internal API                                                                                                                                         | Note                                            |

topics/appendix/api_notable/api_notable_list_2019.md

@@ -1,7 +1,7 @@
-# Notable Changes in IntelliJ Platform and Plugins API 2019.*
-
 <!-- Copyright 2000-2023 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. -->
 
+# Notable Changes in IntelliJ Platform and Plugins API 2019.*
+
 <link-summary>List of known Notable API Changes in 2019.*</link-summary>
 
 ## 2019.3
@@ -40,7 +40,7 @@ Quickfixes for file-level notifications
 : Consistent with other quickfixes, the menu now shows names of fixes, not names of problems themselves. [Issue](https://youtrack.jetbrains.com/issue/IDEA-216731)
 
 Create HTML representation of code
-: Use `com.intellij.openapi.editor.richcopy.HtmlSyntaxInfoUtil` to create Lexer-based highlighted code samples, e.g. for usage in documentation.
+: Use `com.intellij.openapi.editor.richcopy.HtmlSyntaxInfoUtil` to create Lexer-based highlighted code samples, e.g., for usage in documentation.
 
 <ui-path>View | Appearance | Details in Tree Views</ui-path>
 : Toggles showing additional details in UI (e.g. modification timestamp in Project View) see `UISettings.getShowInplaceComments()`.
@@ -63,10 +63,10 @@ New API for Editor Inlay Hints
 `com.intellij.openapi.fileTypes.FileTypeFactory` deprecated
 : When registering file type via file extension, pattern or exact file name matching, use `com.intellij.fileType` extension point instead (see [Sample](language_and_filetype.md#register-the-filetype)).
 
-`@org.jetbrains.annotations.ApiStatus.NonExtendable`
+`org.jetbrains.annotations.ApiStatus.@NonExtendable`
 : Indicates that the annotated API class, interface, or method must not get extended, implemented, or overridden by external plugins but can only be obtained or instantiated for classes and interfaces, or called for methods.
 
-`@org.jetbrains.annotations.ApiStatus.OverrideOnly`
+`org.jetbrains.annotations.ApiStatus.@OverrideOnly`
 : Indicates that the annotated method is part of SPI (Service Provider Interface), which is intended to be only implemented or overridden but never called by external plugins.
 
 `com.intellij.util.Query.forEach`
@@ -90,14 +90,14 @@ Unbundled plugins
 `com.intellij.testFramework.InspectionTestCase` changed to light test
 : Use dedicated `ProjectDescriptor` or rollback project setup changes in `tearDown()` (see [Light and Heavy Tests](light_and_heavy_tests.md)).
 
-`@org.jetbrains.annotations.ApiStatus.AvailableSince`
+`org.jetbrains.annotations.ApiStatus.@AvailableSince`
 : External annotations for the IntelliJ Platform are generated and attached to plugin projects automatically (replacing `@since` Javadoc).
 
-`@org.jetbrains.annotations.ApiStatus.ScheduledForRemoval`
+`org.jetbrains.annotations.ApiStatus.@ScheduledForRemoval`
 : External annotations for the IntelliJ Platform are generated and attached to plugin projects automatically. This allows highlighting of API, which has been removed in newer platform versions.
 
-`@org.jetbrains.annotations.ApiStatus.Internal`
-: Indicates that the annotated element must not be considered as a public API. Do not use outside of the IntelliJ Platform. [Issue](https://youtrack.jetbrains.com/issue/IDEA-211175)
+`org.jetbrains.annotations.ApiStatus.@Internal`
+: Indicates that the annotated element must not be considered as a public API. Do not use outside of the IntelliJ Platform, see [](api_internal.md).
 
 `PsiReferenceProvider` assert underlying element
 : Assert references are created for the given underlying `PsiElement`. [Issue](https://youtrack.jetbrains.com/issue/IDEA-203954)

topics/appendix/resources/explore_api.md

@@ -145,11 +145,11 @@ If you want to implement a functionality that is similar to an existing IDE feat
 
 ### 2.6 Refrain from Using Internal Classes
 
-As a general remark, the use of implementation classes is strongly discouraged (i.e. classes ending with `Impl` in their name,
+As a general remark, the use of implementation classes is strongly discouraged (i.e., classes ending with `Impl` in their name,
 located under `impl` package, or included in <path>*-impl.jar</path>).
 
-Also, API annotated with
-[`org.jetbrains.annotations.ApiStatus.Internal`](https://github.com/JetBrains/java-annotations/blob/master/common/src/main/java/org/jetbrains/annotations/ApiStatus.java)
+API annotated with
+[`ApiStatus.@Internal`](%gh-java-annotations%/common/src/main/java/org/jetbrains/annotations/ApiStatus.java)
 must not be used, see [](api_internal.md) for more details and replacements.
 
 ## 3 Tools and References

topics/appendix/verifying_plugin_compatibility.md

@@ -1,12 +1,12 @@
-# Verifying Plugin Compatibility
-
 <!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
+# Verifying Plugin Compatibility
+
 <link-summary>Tooling for ensuring compatibility.</link-summary>
 
 Please see [](api_changes_list.md) for known breaking changes.
 
-For API annotated with `ApiStatus.@Internal`, see [](api_internal.md) for more details and replacements.
+For API annotated with [`ApiStatus.@Internal`](%gh-java-annotations%/common/src/main/java/org/jetbrains/annotations/ApiStatus.java), see [](api_internal.md) for more details and replacements.
 
 ## Plugin Verifier
 
@@ -27,7 +27,7 @@ In other cases, [intellij-plugin-verifier](https://github.com/JetBrains/intellij
 
 ## IDE Support
 
-The status of an API is marked using various annotations defined in [`ApiStatus`](https://github.com/JetBrains/java-annotations/blob/master/common/src/main/java/org/jetbrains/annotations/ApiStatus.java), please see their Javadoc for more details.
+The status of an API is marked using various annotations defined in [`ApiStatus`](%gh-java-annotations%/common/src/main/java/org/jetbrains/annotations/ApiStatus.java), please see their doc for more details.
 Use highlighting available via dedicated [IDE inspections](https://www.jetbrains.com/help/idea/code-inspection.html) as noted below to prevent problems as early as possible.
 
 ### Unstable API
@@ -67,6 +67,6 @@ Inspection: <control>Plugin DevKit | Plugin descriptor | Plugin.xml validity</co
 A plugin might specify a [compatibility range](build_number_ranges.md) including releases where some API is not available.
 Under the hood, it uses an artifact containing generated data via `ApiStatus.@AvailableSince`, which is automatically attached to the project.
 
-NOTE: If values are not specified directly in [<path>plugin.xml</path>](plugin_configuration_file.md) (e.g., when providing values via [](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) Gradle task), they must be set explicitly in the inspection's settings.
+> If values are not specified directly in [<path>plugin.xml</path>](plugin_configuration_file.md) (e.g., when providing values via [](tools_gradle_intellij_plugin.md#tasks-patchpluginxml) Gradle task), they must be set explicitly in the inspection's settings.
 
 Inspection: <control>Plugin DevKit | Code | Usage of IntelliJ API not available in older IDEs</control>

topics/basics/plugin_structure/plugin_extensions.md

@@ -131,8 +131,8 @@ Property name `language` (or ending in `*Language`, 2020.2+) resolves to all pre
 
 Similarly, `action` resolves to all registered [`<action>`](plugin_configuration_file.md#idea-plugin__actions__action) IDs.
 
-Specifying `@org.jetbrains.annotations.Nls` validates a UI `String` capitalization according to the text property `Capitalization` enum value (2019.2 and later).
+Annotating with [`@Nls`](%gh-java-annotations%/common/src/main/java/org/jetbrains/annotations/Nls.java) validates a UI `String` capitalization according to the text property `Capitalization` enum value (2019.2 and later).
 
-Properties marked as `@Deprecated` or annotated with any of [`ApiStatus`](https://github.com/JetBrains/java-annotations/blob/master/common/src/main/java/org/jetbrains/annotations/ApiStatus.java) `@Internal`, `@Experimental`, `@ScheduledForRemoval`, or `@Obsolete` will be highlighted accordingly.
+Properties marked as `@Deprecated` or annotated with any of [`ApiStatus`](%gh-java-annotations%/common/src/main/java/org/jetbrains/annotations/ApiStatus.java) `@Internal`, `@Experimental`, `@ScheduledForRemoval`, or `@Obsolete` will be highlighted accordingly.
 
 Attributes with `Enum` type support code insight with _lowerCamelCased_ notation (2020.1 and later). Note: these must not override `toString()`.

topics/basics/testing_plugins/testing_faq.md

@@ -1,7 +1,7 @@
-# Testing FAQ
-
 <!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
 
+# Testing FAQ
+
 <link-summary>Common questions and issues for testing plugins.</link-summary>
 
 This page lists a number of common questions/issues and techniques useful for testing plugins.
@@ -121,9 +121,9 @@ Set system property `idea.split.test.logs` to `true` to generate separate test l
 
 ### How to mark test-only elements in production code?
 
-Annotate with [`org.jetbrains.annotations.TestOnly`](https://github.com/JetBrains/java-annotations/blob/master/common/src/main/java/org/jetbrains/annotations/TestOnly.java), usages will be highlighted via inspection <control>JVM languages | Test-only usage in production code</control>.
+Annotate with [`@TestOnly`](%gh-java-annotations%/common/src/main/java/org/jetbrains/annotations/TestOnly.java), usages will be highlighted via inspection <control>JVM languages | Test-only usage in production code</control>.
 
-To mark members whose visibility is higher than necessary to be used from tests, use [`org.jetbrains.annotations.VisibleForTesting`](https://github.com/JetBrains/java-annotations/blob/master/common/src/main/java/org/jetbrains/annotations/VisibleForTesting.java)
+To mark members whose visibility is higher than necessary to be used from tests, use [`@VisibleForTesting`](%gh-java-annotations%/common/src/main/java/org/jetbrains/annotations/VisibleForTesting.java)
 
 ### How to run tests for all files in a directory?
 

v.list

@@ -18,6 +18,7 @@
   <var name="gh-ij-plugins-master" value="https://github.com/JetBrains/intellij-plugins/tree/master"/>
 
   <var name="gh-jcef" value="https://github.com/JetBrains/jcef/tree/master/java"/>
+  <var name="gh-java-annotations" value="https://github.com/JetBrains/java-annotations/tree/master/"/>
 
   <var name="gh-ijpgp" value="https://github.com/JetBrains/gradle-intellij-plugin/blob/2.0"/>
   <var name="gh-pv" value="https://github.com/JetBrains/intellij-plugin-verifier/blob/master"/>