1 /* 2 * Copyright (C) 2018 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 com.android.tools.metalava.model 18 19 /** Various places where a given annotation can be written */ 20 enum class AnnotationTarget { 21 /** Write the annotation into the signature file */ 22 SIGNATURE_FILE, 23 /** Write the annotation into stub source files */ 24 SDK_STUBS_FILE, 25 /** Write the annotation into doc stub source files */ 26 DOC_STUBS_FILE, 27 /** Write the annotation into external annotation files */ 28 EXTERNAL_ANNOTATIONS_FILE, 29 ; 30 31 /** Is this target a stubs file? */ isStubsFilenull32 fun isStubsFile(): Boolean { 33 return this == SDK_STUBS_FILE || this == DOC_STUBS_FILE 34 } 35 } 36 37 /** Don't write this annotation anywhere; it is not API significant. */ 38 val NO_ANNOTATION_TARGETS = emptySet<AnnotationTarget>() 39 40 /** 41 * Annotation is API significant: write it into the signature file and stub source code. This would 42 * normally be the case for all (API significant) class-retention annotations, but unfortunately due 43 * to apt (the annotation processor) attempting to load all classes for annotation references that 44 * it comes across, that means we cannot compile the stubs with the androidx annotations and leave 45 * those in the SDK; apt would also need to have androidx on the classpath. So instead we put all 46 * these annotations (except for @RecentlyNullable and @RecentlyNonNull, which are not part of 47 * androidx, and which we include as package private in the SDK, something we cannot do with the 48 * others since their class definitions conflict with the real androidx library when present) into 49 * the external annotations file. 50 * 51 * Also includes documentation stubs. 52 */ 53 val ANNOTATION_IN_ALL_STUBS = 54 setOf( 55 AnnotationTarget.SIGNATURE_FILE, 56 AnnotationTarget.SDK_STUBS_FILE, 57 AnnotationTarget.DOC_STUBS_FILE, 58 ) 59 60 /** 61 * Like [ANNOTATION_IN_ALL_STUBS], but limited to documentation stubs, not included in SDK stubs. 62 * These are also placed in external annotations since they don't appear in the SDK. 63 * 64 * Example: NonNull. 65 */ 66 val ANNOTATION_IN_DOC_STUBS_AND_EXTERNAL = 67 setOf( 68 AnnotationTarget.SIGNATURE_FILE, 69 AnnotationTarget.DOC_STUBS_FILE, 70 AnnotationTarget.EXTERNAL_ANNOTATIONS_FILE, 71 ) 72 73 /** 74 * Annotation is API significant: write it into the signature file and into external annotations 75 * file. 76 */ 77 val ANNOTATION_EXTERNAL = 78 setOf( 79 AnnotationTarget.SIGNATURE_FILE, 80 AnnotationTarget.EXTERNAL_ANNOTATIONS_FILE, 81 ) 82 83 /** Write it only into the external annotations file, not the signature file */ 84 val ANNOTATION_EXTERNAL_ONLY = setOf(AnnotationTarget.EXTERNAL_ANNOTATIONS_FILE) 85 86 /** Write it only into the signature file */ 87 val ANNOTATION_SIGNATURE_ONLY = setOf(AnnotationTarget.SIGNATURE_FILE) 88 89 /** Write it only into the stubs, but don't track it in the signature files. */ 90 val ANNOTATION_STUBS_ONLY = 91 setOf( 92 AnnotationTarget.SDK_STUBS_FILE, 93 AnnotationTarget.DOC_STUBS_FILE, 94 ) 95 96 /** Write it only into the SDK stubs, but don't track it in the signature files. */ 97 val ANNOTATION_SDK_STUBS_ONLY = setOf(AnnotationTarget.SDK_STUBS_FILE) 98