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