Add InternalAPIMarker annotation for internal API boundaries#230
Add InternalAPIMarker annotation for internal API boundaries#230twisti-dev merged 2 commits intoversion/1.21.11from
Conversation
There was a problem hiding this comment.
Pull request overview
Introduces a new public marker annotation (InternalAPIMarker) intended to designate “internal API” opt-in annotations for improved visibility control in IDE tooling, and bumps the project version accordingly.
Changes:
- Added
InternalAPIMarkerannotation with KDoc describing intended usage. - Updated the public API surface file (
.api) to include the new annotation. - Bumped project version from
1.21.11-2.59.4to1.21.11-2.60.0.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| surf-api-shared/surf-api-shared-public/src/main/kotlin/dev/slne/surf/surfapi/shared/api/annotation/InternalAPIMarker.kt | Adds the new marker annotation and its documentation. |
| surf-api-shared/surf-api-shared-public/api/surf-api-shared-public.api | Declares the new annotation in the published API surface. |
| gradle.properties | Updates the project version to reflect the API addition. |
| * annotation class InternalSurfAPI | ||
| * | ||
| * @InternalSurfAPI |
There was a problem hiding this comment.
The KDoc example uses InternalSurfAPI, but the existing internal opt-in annotation in this repo is named InternalSurfApi. Using a different name in the example is confusing for consumers—either align the example with the actual InternalSurfApi name or make it a clearly generic placeholder name (e.g., InternalApi).
| * annotation class InternalSurfAPI | |
| * | |
| * @InternalSurfAPI | |
| * annotation class InternalSurfApi | |
| * | |
| * @InternalSurfApi |
| * fun internalFunction() { ... } | ||
| * ``` | ||
| */ | ||
| @Target(AnnotationTarget.ANNOTATION_CLASS) |
There was a problem hiding this comment.
InternalAPIMarker currently uses the default annotation retention (RUNTIME). If this marker is only meant for IDE/static analysis, consider setting an explicit retention (typically AnnotationRetention.BINARY) to avoid carrying it into runtime reflection unnecessarily and to document the intended usage.
| @Target(AnnotationTarget.ANNOTATION_CLASS) | |
| @Target(AnnotationTarget.ANNOTATION_CLASS) | |
| @Retention(AnnotationRetention.BINARY) |
This pull request introduces a new marker annotation for internal API boundaries and updates the project version. The main focus is on improving API visibility control for consumers by providing a standardized way to mark internal APIs.
API Visibility Improvements
InternalAPIMarkerannotation class insurf-api-shared/surf-api-shared-public/src/main/kotlin/dev/slne/surf/surfapi/shared/api/annotation/InternalAPIMarker.kt, including documentation explaining its usage for marking internal API annotations.InternalAPIMarkeras a public abstract interface annotation in the API definition filesurf-api-shared/surf-api-shared-public/api/surf-api-shared-public.api.Version Update
gradle.propertiesfrom1.21.11-2.59.4to1.21.11-2.60.0.