From b92cbd4bad02d6b3d2e39a86ef7851bd08ed6cb2 Mon Sep 17 00:00:00 2001
From: Sergey Patrikeev <Sergey.Patrikeev@jetbrains.com>
Date: Wed, 2 Oct 2019 13:42:45 +0300
Subject: [PATCH] ApiStatus: clarify Javadoc on how Experimental and Internal
 annotations are propagated to members.

GitOrigin-RevId: c1598acaf95b1f92c1da564cc6b941d37b5fdfcc
---
 .../src/org/jetbrains/annotations/ApiStatus.java   | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/platform/util/src/org/jetbrains/annotations/ApiStatus.java b/platform/util/src/org/jetbrains/annotations/ApiStatus.java
index 9580900795cf..c2164b6cde63 100644
--- a/platform/util/src/org/jetbrains/annotations/ApiStatus.java
+++ b/platform/util/src/org/jetbrains/annotations/ApiStatus.java
@@ -14,6 +14,13 @@ public final class ApiStatus {
    *
    * <p>It's safe to use an element marked with this annotation if the usage is located in the same sources codebase as the declaration. However,
    * if the declaration belongs to an external library such usages may lead to problems when the library will be updated to another version.</p>
+   *
+   * <p>If a package is marked with this annotation, all its containing classes are considered experimental.
+   * Subpackages of this package are not affected and should be marked independently.</p>
+   *
+   * <p>If a type is marked with this annotation, all its members are considered experimental, but its inheritors are not.</p>
+   *
+   * <p>If a method is marked with this annotation, overriding methods are not considered experimental.</p>
    */
   @Documented
   @Retention(RetentionPolicy.CLASS)
@@ -26,6 +33,13 @@ public final class ApiStatus {
    * 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 module, but it must not be used outside of that module. Such elements
    * may be renamed, changed or removed in future versions.
+   *
+   * <p>If a package is marked with this annotation, all its containing classes are considered internal.
+   * Subpackages of this package are not affected and should be marked independently.</p>
+   *
+   * <p>If a type is marked with this annotation, all its members are considered internal, but its inheritors are not.</p>
+   *
+   * <p>If a method is marked with this annotation, overriding methods are not considered internal.</p>
    */
   @Documented
   @Retention(RetentionPolicy.CLASS)