1 /*
2  * Copyright 2020 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package androidx.annotation
18 
19 import kotlin.annotation.Retention
20 import kotlin.annotation.Target
21 
22 /**
23  * Denotes that the annotated element is a marker of an opt-in API.
24  *
25  * Any declaration annotated with this marker is considered part of an unstable or otherwise
26  * non-standard API surface and its call sites should accept the opt-in aspect of it either by using
27  * [OptIn] or by being annotated with that marker themselves, effectively causing further
28  * propagation of that opt-in aspect.
29  *
30  * ```
31  * // Marker definition
32  *
33  * @Retention(CLASS)
34  * @Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE})
35  * @RequiresOptIn(level = Level.ERROR)
36  * public @interface ExperimentalDateTime {}
37  *
38  * @ExperimentalDateTime
39  * public class DateProvider {
40  *   // ...
41  * }
42  *
43  * // Client code
44  *
45  * int getYear() {
46  *   DateProvider provider; // Error: DateProvider is experimental
47  *   // ...
48  * }
49  *
50  * @ExperimentalDateTime
51  * Date getDate() {
52  *   DateProvider provider; // OK: the function is marked as experimental
53  *   // ...
54  * }
55  *
56  * void displayDate() {
57  *   System.out.println(getDate()); // Error: getDate() is experimental, acceptance is required
58  * }
59  * ```
60  *
61  * To configure project-wide opt-in, specify the `opt-in` option value in `lint.xml` as a
62  * comma-delimited list of opted-in annotations:
63  * ```
64  * <lint>
65  *   <issue id="$issueId">
66  *     <option name="opt-in" value="com.foo.ExperimentalBarAnnotation" />
67  *   </issue>
68  * </lint>
69  * ```
70  */
71 @Retention(AnnotationRetention.BINARY)
72 @Target(AnnotationTarget.ANNOTATION_CLASS)
73 public annotation class RequiresOptIn(
74     /** Defines the reporting level for incorrect usages of this opt-in API. */
75     val level: Level = Level.ERROR,
76     /**
77      * Message to be reported on usages of API without an explicit opt-in, or empty string for the
78      * default message. The default message is: "This declaration is experimental and its usage
79      * should be marked with 'Marker' or '@OptIn(Marker::class)'", where Marker is the opt-in
80      * requirement marker.
81      */
82     val message: String = ""
83 ) {
84     /**
85      * Severity of the diagnostic that should be reported on usages of opt-in API which did not
86      * explicitly accept the opt-in aspect of that API either by:
87      * <ul>
88      * <li>Propagating the opt-in aspect by annotating the usage with the marker annotation, thus
89      *   becoming part of the marked opt-in API surface <i>or</i>
90      * <li>Suppressing propagation of the opt-in aspect by annotating the usage with [OptIn] and
91      *   specifying the marker annotation
92      */
93     public enum class Level {
94         /** Specifies that a warning should be reported on incorrect usages of this opt-in API. */
95         WARNING,
96 
97         /** Specifies that an error should be reported on incorrect usages of this opt-in API. */
98         ERROR
99     }
100 }
101