From 6fffeceb0dbd6d7ac00544c0e7dd8d18d2666b23 Mon Sep 17 00:00:00 2001
From: Konrad Malawski <konrad.malawski@project13.pl>
Date: Fri, 6 Jan 2017 11:00:05 +0100
Subject: [PATCH] +act #22109 add documentation annotations in akka.annotation

---
 .../java/akka/annotation/ApiMayChange.java    | 29 +++++++++++++++++++
 .../java/akka/annotation/DoNotInherit.java    | 27 +++++++++++++++++
 .../java/akka/annotation/InternalApi.java     | 24 +++++++++++++++
 3 files changed, 80 insertions(+)
 create mode 100644 akka-actor/src/main/java/akka/annotation/ApiMayChange.java
 create mode 100644 akka-actor/src/main/java/akka/annotation/DoNotInherit.java
 create mode 100644 akka-actor/src/main/java/akka/annotation/InternalApi.java

diff --git a/akka-actor/src/main/java/akka/annotation/ApiMayChange.java b/akka-actor/src/main/java/akka/annotation/ApiMayChange.java
new file mode 100644
index 0000000000..c39784e9eb
--- /dev/null
+++ b/akka-actor/src/main/java/akka/annotation/ApiMayChange.java
@@ -0,0 +1,29 @@
+/*
+ * Copyright (C) 2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+
+package akka.annotation;
+
+import java.lang.annotation.*;
+
+/**
+ * Marks APIs that are meant to evolve towards becoming stable APIs, but are not stable APIs yet.
+ * 
+ * Evolving interfaces MAY change from one patch release to another (i.e. 2.4.10 to 2.4.11) without up-front notice.
+ * A best-effort approach is taken to not cause more breakage than really neccessary, and usual deprecation techniques 
+ * are utilised while evolving these APIs, however there is NO strong guarantee regarding the source or binary 
+ * compatibility of APIs marked using this annotation. 
+ * 
+ * It MAY also change when promoting the API to stable, for example such changes may include removal of deprecated 
+ * methods that were introduced during the evolution and final refactoring that were deferred because they would 
+ * have introduced to much breaking changes during the evolution phase. 
+ * 
+ * Promoting the API to stable MAY happen in a patch release.
+ * 
+ * It is encouraged to document in ScalaDoc how exactly this API is expected to evolve.
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS) // to be accessible by MiMa
+@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.TYPE, ElementType.PACKAGE})
+public @interface ApiMayChange {
+}
diff --git a/akka-actor/src/main/java/akka/annotation/DoNotInherit.java b/akka-actor/src/main/java/akka/annotation/DoNotInherit.java
new file mode 100644
index 0000000000..ef54442e0b
--- /dev/null
+++ b/akka-actor/src/main/java/akka/annotation/DoNotInherit.java
@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+
+package akka.annotation;
+
+import java.lang.annotation.*;
+
+/**
+ * Marks APIs that are designed under an closed-world assumption for and are NOT meant to be extended by user-code.
+ * It is fine to extend these classes within Akka itself however.
+ * <p/>
+ * This is most useful for binary compatibility purposes when a set of classes and interfaces assume a "closed world" 
+ * between them, and gain the ability to add methods to the interfaces without breaking binary compatibility for 
+ * users of this code. Specifically this assumption may be understood intuitively: as all classes that implement this 
+ * interface are in this compilation unit / artifact, it is impossible to obtain a "old" class with a "new" interface,
+ * as they are part of the same dependency.
+ * <p/>
+ * Notable examples of such API include the FlowOps trait in Akka Streams or Akka HTTP model interfaces,
+ * which extensively uses inheritance internally, but are not meant for extension by user code.
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS) // to be accessible by MiMa
+@Target({ElementType.TYPE})
+public @interface DoNotInherit {
+  String description();
+}
diff --git a/akka-actor/src/main/java/akka/annotation/InternalApi.java b/akka-actor/src/main/java/akka/annotation/InternalApi.java
new file mode 100644
index 0000000000..21bac1df74
--- /dev/null
+++ b/akka-actor/src/main/java/akka/annotation/InternalApi.java
@@ -0,0 +1,24 @@
+/*
+ * Copyright (C) 2017 Lightbend Inc. <http://www.lightbend.com>
+ */
+
+package akka.annotation;
+
+import java.lang.annotation.*;
+
+/**
+ * Marks APIs that are considered internal to Akka and may change at any point in time without any warning.
+ * <p/>
+ * For example, this annotation should be used when the Scala {@code private[akka]} access restriction is used,
+ * as Java has no way of representing this package restricted access and such methods and classes are represented
+ * as {@code public} in byte-code.
+ * <p/>
+ * If a method/class annotated with this method has a javadoc/scaladoc comment, the first line MUST include 
+ * {@code INTERNAL API} in order to be easily identifiable from generated documentation. Additional information
+ * may be put on the same line as the INTERNAL API comment in order to clarify further.
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS) // to be accessible by MiMa
+@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.TYPE, ElementType.PACKAGE})
+public @interface InternalApi {
+}