1 /* 2 * Copyright (C) 2024 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.model.api.surface.ApiVariant 20 import com.android.tools.metalava.model.api.surface.ApiVariantSet 21 import com.android.tools.metalava.model.api.surface.MutableApiVariantSet 22 23 /** 24 * An [Item] that can be selected to be a part of an API in its own right. 25 * 26 * e.g. a [MethodItem] is selectable because while a method's [MethodItem.containingClass] has to be 27 * part of the same API just because the [ClassItem] is selected does not mean that a [MethodItem] 28 * has to be. 29 * 30 * Conversely, a [ParameterItem] is not selectable because it cannot be selected on its own, it is 31 * an indivisible part of the [ParameterItem.containingCallable]. 32 */ 33 interface SelectableItem : Item { 34 /** The [ApiVariant]s for which this [Item] has been selected. */ 35 var selectedApiVariants: ApiVariantSet 36 37 /** 38 * Mutate [selectedApiVariants]. 39 * 40 * Provides a [MutableApiVariantSet] of the [selectedApiVariants] that can be modified by 41 * [mutator]. Once the mutator exits [selectedApiVariants] will be updated. The 42 * [MutableApiVariantSet] must not be accessed from outside [mutator]. 43 */ mutateSelectedApiVariantsnull44 fun mutateSelectedApiVariants(mutator: MutableApiVariantSet.() -> Unit) 45 46 /** Whether this element will be printed in the signature file */ 47 var emit: Boolean 48 49 /** 50 * Whether this element was originally hidden with @hide/@Hide. The [hidden] property tracks 51 * whether it is *actually* hidden, since elements can be unhidden via show annotations, etc. 52 * 53 * @see variantSelectors 54 */ 55 val originallyHidden: Boolean 56 57 /** 58 * Whether this element has been hidden with @hide/@Hide (or after propagation, in some 59 * containing class/pkg) 60 * 61 * @see variantSelectors 62 */ 63 val hidden: Boolean 64 65 /** 66 * Tracks the properties that determine whether this [Item] will be selected for each API 67 * variant. 68 * 69 * @see originallyHidden 70 * @see hidden 71 * @see removed 72 */ 73 val variantSelectors: ApiVariantSelectors 74 75 /** 76 * Recursive check to see if this item or any of its parents (containing class, containing 77 * package) are hidden 78 */ 79 fun hidden(): Boolean { 80 return hidden || parent()?.hidden() ?: false 81 } 82 83 /** 84 * Whether this element has been removed with @removed/@Remove (or after propagation, in some 85 * containing class) 86 * 87 * @see variantSelectors 88 */ 89 val removed: Boolean 90 91 /** True if this item is either hidden or removed */ isHiddenOrRemovednull92 fun isHiddenOrRemoved(): Boolean = hidden || removed 93 94 /** Determines whether this item will be shown as part of the API or not. */ 95 val showability: Showability 96 97 /** 98 * Returns true if this item has any show annotations. 99 * 100 * See [Showability.show] 101 */ 102 fun hasShowAnnotation(): Boolean = showability.show() 103 104 /** Returns true if this modifier list contains any hide annotations */ 105 fun hasHideAnnotation(): Boolean = codebase.annotationManager.hasHideAnnotations(modifiers) 106 107 /** Override to specialize return type. */ 108 override fun findCorrespondingItemIn( 109 codebase: Codebase, 110 superMethods: Boolean, 111 duplicate: Boolean, 112 ): SelectableItem? 113 } 114