1 /* 2 * Copyright (C) 2017 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 18 19 const val COMPAT_MODE_BY_DEFAULT = true 20 21 /** 22 * The old API generator code had a number of quirks. Initially we want to simulate these 23 * quirks to produce compatible signature files and APIs, but we want to track what these quirks 24 * are and be able to turn them off eventually. This class offers more fine grained control 25 * of these compatibility behaviors such that we can enable/disable them selectively 26 */ 27 var compatibility: Compatibility = Compatibility() 28 29 class Compatibility( 30 /** Whether compatibility is generally on */ 31 val compat: Boolean = COMPAT_MODE_BY_DEFAULT 32 ) { 33 34 /** In signature files, use "implements" instead of "extends" for the super class of 35 * an interface */ 36 var extendsForInterfaceSuperClass: Boolean = compat 37 38 /** In signature files, refer to annotations as an "abstract class" instead of an "@interface" 39 * and implementing this interface: java.lang.annotation.Annotation */ 40 var classForAnnotations: Boolean = compat 41 42 /** Add in explicit `valueOf` and `values` methods into enum classes */ 43 var defaultEnumMethods: Boolean = compat 44 45 /** Whether signature files should contain annotation default values (as is already 46 * done for field default values) */ 47 var includeAnnotationDefaults: Boolean = !compat 48 49 /** In signature files, refer to enums as "class" instead of "enum" */ 50 var classForEnums: Boolean = compat 51 52 /** Whether to use a nonstandard, compatibility modifier order instead of the Java canonical order. 53 * ("deprecated" isn't a real modifier, so in "standard" mode it's listed first, as if it was the 54 * `@Deprecated` annotation before the modifier list */ 55 var nonstandardModifierOrder: Boolean = compat 56 57 /** Whether to include instance methods in annotation classes for the annotation properties */ 58 var skipAnnotationInstanceMethods: Boolean = compat 59 60 /** 61 * In signature files, whether interfaces should also be described as "abstract" 62 */ 63 var abstractInInterfaces: Boolean = compat 64 65 /** 66 * In signature files, whether annotation types should also be described as "abstract" 67 */ 68 var abstractInAnnotations: Boolean = compat 69 70 /** 71 * In signature files, whether interfaces can be listed as final 72 */ 73 var finalInInterfaces: Boolean = compat 74 75 /** 76 * In this signature 77 * public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X { 78 * doclava1 would treat this as "throws Throwable" instead of "throws X". This variable turns on 79 * this compat behavior. 80 * */ 81 var useErasureInThrows: Boolean = compat 82 83 /** 84 * Whether throws classes in methods should be filtered. This should definitely 85 * be the case, but doclava1 doesn't. Note that this only applies to signature 86 * files, not stub files. 87 */ 88 var filterThrowsClasses: Boolean = !compat 89 90 /** Format `Map<K,V>` as `Map<K, V>` */ 91 var spaceAfterCommaInTypes: Boolean = compat 92 93 /** 94 * Doclava1 omits type parameters in interfaces (in signature files, not in stubs) 95 */ 96 var omitTypeParametersInInterfaces: Boolean = compat 97 98 /** Force methods named "values" in enums to be marked final. This was done by 99 * doclava1 with this comment: 100 * 101 * Explicitly coerce 'final' state of Java6-compiled enum values() method, 102 * to match the Java5-emitted base API description. 103 * 104 **/ 105 var forceFinalInEnumValueMethods: Boolean = compat 106 107 /** Whether signature files and stubs should contain annotations */ 108 var annotationsInSignatures: Boolean = !compat 109 110 /** 111 * When a public class implementing a public interface inherits the implementation 112 * of a method in that interface from a hidden super class, the method must be 113 * included in the stubs etc (since otherwise subclasses would believe they need 114 * to implement that method and can't just inherit it). However, doclava1 does not 115 * list these methods. This flag controls this compatibility behavior. 116 * Not that this refers only to the signature files, not the stub file generation. 117 * 118 * An example is StringBuilder#setLength. 119 */ 120 var skipInheritedMethods: Boolean = compat 121 122 /** 123 * Similar to [skipInheritedMethods], but for field constants. 124 */ 125 var skipInheritedConstants: Boolean = compat 126 127 /** 128 * Whether to include parameter names in the signature file 129 */ 130 var parameterNames: Boolean = !compat 131 132 /** 133 * *Some* signatures for doclava1 wrote "<?>" as "<? extends java.lang.Object>", 134 * which is equivalent. Metalava does not do that. This flags ensures that the 135 * signature files look like the old ones for the specific methods which did this. 136 */ 137 var includeExtendsObjectInWildcard = compat 138 139 /** 140 * Whether deprecation should be shown in signature files as an annotation 141 * instead of a pseudo-modifier 142 */ 143 var deprecatedAsAnnotation = !compat 144 145 /** Whether synchronized should be part of the output */ 146 var includeSynchronized = compat 147 148 /** Whether we should omit common packages such as java.lang.* and kotlin.* from signature output */ 149 var omitCommonPackages = !compat 150 151 /** Whether we should explicitly include retention when class even if not explicitly defined */ 152 var explicitlyListClassRetention = !compat 153 154 /** 155 * If true, a @Deprecated class will automatically deprecate all its inner classes 156 * as well. 157 */ 158 var propagateDeprecatedInnerClasses = !compat 159 160 /** 161 * If true, a @Deprecated class will automatically deprecate all members (not 162 * including inner classes; for that see [propagateDeprecatedInnerClasses]) as well. 163 */ 164 var propagateDeprecatedMembers = !compat 165 166 /** 167 * If an overriding method differs from its super method only by final or deprecated 168 * and the containing class is final or deprecated, skip it in the signature file 169 */ 170 var hideDifferenceImplicit = !compat 171 172 /** Whether inner enums should be listed as static in the signature file. */ 173 var staticEnums = compat 174 175 /** 176 * The -new_api flag in API check (which generates an XML diff of the differences 177 * between two APIs) in doclava was ignoring fields. This flag controls whether 178 * we do the same. 179 */ 180 var includeFieldsInApiDiff = !compat 181 182 /** 183 * Whether to escape the > character in JDiff XML files. The XML spec does not require 184 * this but doclava does it. 185 */ 186 var xmlEscapeGreaterThan = compat 187 188 /** 189 * When producing JDiff output for field arrays but where we 190 * do not have the value, emit "null" into the JDiff report. This isn't right but matches 191 * what doclava did. 192 */ 193 var xmlShowArrayFieldsAsNull = compat 194 195 /** 196 * Doclava was missing enum fields in JDiff reports 197 */ 198 var xmlSkipEnumFields = compat 199 200 /** 201 * Doclava was missing annotation instance methods in JDiff reports 202 */ 203 var xmlSkipAnnotationMethods = compat 204 205 /** Doclava lists character field values as integers instead of chars */ 206 var xmlCharAsInt = compat 207 208 /** 209 * Doclava listed the superclass of annotations as 210 * java.lang.Object. 211 */ 212 var xmlAnnotationAsObject = compat 213 214 // Other examples: sometimes we sort by qualified name, sometimes by full name 215 }