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 /** Write the annotation for internal purposes (e.g. cloning a method) */ 30 INTERNAL; 31 32 /** Is this target a stubs file? */ isStubsFilenull33 fun isStubsFile(): Boolean { 34 return this == SDK_STUBS_FILE || this == DOC_STUBS_FILE 35 } 36 } 37 38 /** Don't write this annotation anywhere; it is not API significant. */ 39 val NO_ANNOTATION_TARGETS = setOf(AnnotationTarget.INTERNAL) 40 41 /** 42 * Annotation is API significant: write it into the signature file and stub source code. 43 * This would normally be the case for all (API significant) class-retention annotations, 44 * but unfortunately due to apt (the annotation processor) attempting to load all 45 * classes for annotation references that it comes across, that means we cannot 46 * compile the stubs with the androidx annotations and leave those in the SDK; apt 47 * would also need to have androidx on the classpath. So instead we put all these 48 * annotations (except for @RecentlyNullable and @RecentlyNonNull, which are not part 49 * of androidx, and which we include as package private in the SDK, something we cannot 50 * do with the others since their class definitions conflict with the real androidx library 51 * when present) into the external annotations file. 52 * 53 * Also includes documentation stubs. 54 */ 55 val ANNOTATION_IN_ALL_STUBS = setOf( 56 AnnotationTarget.SIGNATURE_FILE, 57 AnnotationTarget.SDK_STUBS_FILE, 58 AnnotationTarget.DOC_STUBS_FILE, 59 AnnotationTarget.INTERNAL 60 ) 61 62 /** 63 * Like [ANNOTATION_IN_ALL_STUBS], but limited to SDK stubs, not included in documentation stubs. 64 * Example: RecentlyNonNull. 65 */ 66 val ANNOTATION_IN_SDK_STUBS = setOf( 67 AnnotationTarget.SIGNATURE_FILE, 68 AnnotationTarget.SDK_STUBS_FILE, 69 AnnotationTarget.INTERNAL 70 ) 71 72 /** 73 * Like [ANNOTATION_IN_ALL_STUBS], but limited to documentation stubs, not included in SDK stubs. 74 * These are also placed in external annotations since they don't appear in the SDK. 75 * 76 * Example: NonNull. 77 */ 78 val ANNOTATION_IN_DOC_STUBS_AND_EXTERNAL = setOf( 79 AnnotationTarget.SIGNATURE_FILE, 80 AnnotationTarget.DOC_STUBS_FILE, 81 AnnotationTarget.EXTERNAL_ANNOTATIONS_FILE, 82 AnnotationTarget.INTERNAL 83 ) 84 85 /** Annotation is API significant: write it into the signature file and into external annotations file. */ 86 val ANNOTATION_EXTERNAL = setOf( 87 AnnotationTarget.SIGNATURE_FILE, 88 AnnotationTarget.EXTERNAL_ANNOTATIONS_FILE, 89 AnnotationTarget.INTERNAL 90 ) 91 92 /** Write it only into the external annotations file, not the signature file */ 93 val ANNOTATION_EXTERNAL_ONLY = setOf( 94 AnnotationTarget.EXTERNAL_ANNOTATIONS_FILE, 95 AnnotationTarget.INTERNAL 96 ) 97 98 /** Write it only into the signature file */ 99 val ANNOTATION_SIGNATURE_ONLY = setOf( 100 AnnotationTarget.SIGNATURE_FILE, 101 AnnotationTarget.INTERNAL 102 ) 103 104 /** Write it only into the stubs, but don't track it in the signature files. */ 105 val ANNOTATION_STUBS_ONLY = setOf( 106 AnnotationTarget.SDK_STUBS_FILE, 107 AnnotationTarget.DOC_STUBS_FILE, 108 AnnotationTarget.INTERNAL 109 ) 110 111 /** Write it only into the SDK stubs, but don't track it in the signature files. */ 112 val ANNOTATION_SDK_STUBS_ONLY = setOf( 113 AnnotationTarget.SDK_STUBS_FILE, 114 AnnotationTarget.INTERNAL 115 ) 116