Update Sdk annotations to add Documented annotation and update documentation (#6503)

Author: zoewangg

core/annotations/src/main/java/software/amazon/awssdk/annotations/ReviewBeforeRelease.java

@@ -15,15 +15,23 @@
 
 package software.amazon.awssdk.annotations;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Target;
 
 /**
- * Marker interface for 'internal' APIs that should not be used outside the same module. Breaking
- * changes can and will be introduced to elements marked as {@link SdkInternalApi}. Users of the SDK
- * and the generated clients themselves should not depend on any packages, types, fields,
- * constructors, or methods with this annotation.
+ * Marks APIs that should not be used by SDK users and are internal to the AWS SDK for Java v2, subject to change without notice.
+ * 
+ * <p><b>WARNING:</b> Elements annotated with {@code @SdkInternalApi} are not part of the public API.
+ * They may be modified or removed in any release without warning, including minor and patch releases.
+ * 
+ * <p><b>Intended for:</b> Internal SDK implementation only. This annotation indicates that the
+ * marked element should not be used outside its defining module.
+ * 
+ * @see SdkProtectedApi
+ * @see SdkPublicApi
  */
+@Documented
 @Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD})
 @SdkProtectedApi
 public @interface SdkInternalApi {

core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkInternalApi.java

@@ -19,10 +19,26 @@
 import java.lang.annotation.Target;
 
 /**
- * Marker interface for preview and experimental APIs. Breaking changes may be
- * introduced to elements marked as {@link SdkPreviewApi}. Users of the SDK
- * should assume that anything annotated as preview will change or break, and
- * <b>should not</b> use them in production.
+ * Marks APIs as preview or experimental features that may change or be removed.
+ * 
+ * <p><b>WARNING:</b> Elements annotated with {@code @SdkPreviewApi} are not stable and may
+ * introduce breaking changes in any release, including minor and patch versions. Do not use
+ * preview APIs in production environments.
+ * 
+ * <p><b>Use with caution:</b>
+ * <ul>
+ *   <li>Preview APIs are suitable for testing and providing feedback</li>
+ *   <li>They may change significantly based on user feedback</li>
+ *   <li>They may be promoted to public APIs or removed entirely</li>
+ *   <li>No backward compatibility is guaranteed</li>
+ * </ul>
+ * 
+ * <p><b>Intended for:</b> Early adopters and developers who want to experiment with new features
+ * and provide feedback before they become stable public APIs.
+ * 
+ * @see SdkPublicApi
+ * @see SdkProtectedApi
+ * @see SdkInternalApi
  */
 @Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD})
 @SdkProtectedApi

core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkPreviewApi.java

@@ -15,17 +15,26 @@
 
 package software.amazon.awssdk.annotations;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Target;
 
 /**
- * Marker for elements that should only be accessed by the generated clients and not users of the
- * SDK. Do not make breaking changes to these APIs - they won't directly break customers, but
- * they'll break old versions of generated clients.
- * <p>
- * TODO: Write a linter that makes sure generated code only depends on public or
- * {@code @InternalApi} classes.
+ * Marks APIs that should not be used by SDK users and are intended for SDK internal classes shared across different modules.
+ *
+ * <p><b>IMPORTANT:</b> Elements annotated with {@code @SdkProtectedApi} must maintain backward
+ * compatibility. Breaking changes will break older versions of generated clients, even if they don't directly impact SDK users.
+ *
+ * <p><b>Intended for:</b> Generated service clients and internal SDK modules that support them.
+ * These APIs form the contract between the SDK core and generated code.
+ *
+ * <p><b>Stability guarantee:</b> Protected APIs should not introduce breaking changes, as this
+ * would require regenerating and redeploying all service clients.
+ *
+ * @see SdkInternalApi
+ * @see SdkPublicApi
  */
+@Documented
 @Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD})
 @SdkProtectedApi
 public @interface SdkProtectedApi {

core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkProtectedApi.java

@@ -15,12 +15,30 @@
 
 package software.amazon.awssdk.annotations;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Target;
 
 /**
- * Marker interface for 'public' APIs.
+ * Marks APIs as public and stable for use by SDK users building applications.
+ * 
+ * <p><b>Stability guarantee:</b> Elements annotated with {@code @SdkPublicApi} are backward
+ * compatible.
+ * 
+ * <p><b>Safe to use for:</b>
+ * <ul>
+ *   <li>Application code that depends on the AWS SDK</li>
+ *   <li>Libraries that build on top of the SDK</li>
+ *   <li>Any code requiring stable, long-term API contracts</li>
+ * </ul>
+ * 
+ * <p><b>Intended for:</b> SDK users and external developers. These APIs form the official public
+ * interface of the AWS SDK for Java v2.
+ * 
+ * @see SdkProtectedApi
+ * @see SdkInternalApi
  */
+@Documented
 @Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD})
 @SdkProtectedApi
 public @interface SdkPublicApi {

core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkPublicApi.java

@@ -15,6 +15,7 @@
 
 package software.amazon.awssdk.annotations;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Target;
 
@@ -27,6 +28,7 @@
  * TODO: Write a linter that makes sure only test code depends on methods or constructors annotated
  * with this method
  */
+@Documented
 @Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.FIELD, ElementType.TYPE})
 @SdkProtectedApi
 public @interface SdkTestInternalApi {

core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkTestInternalApi.java

@@ -687,10 +687,10 @@
                         </includeModules>
                         <excludes>
                             <exclude>*.internal.*</exclude>
+                            <!-- TODO remove after release -->
+                            <exclude>software.amazon.awssdk.annotations.ReviewBeforeRelease</exclude>
                             <exclude>software.amazon.awssdk.thirdparty.*</exclude>
                             <exclude>software.amazon.awssdk.regions.*</exclude>
-                            <!-- TODO remove after release -->
-                            <exclude>software.amazon.awssdk.awscore.interceptor.TraceIdExecutionInterceptor</exclude>
                         </excludes>
 
                         <ignoreMissingOldVersion>true</ignoreMissingOldVersion>