1 /* 2 * Copyright 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 androidx.build.doclava 18 19 import java.io.Serializable 20 21 data class ChecksConfig( 22 /** 23 * List of Doclava error codes to treat as errors. 24 * <p> 25 * See {@link com.google.doclava.Errors} for a complete list of error codes. 26 */ 27 val errors: List<Int>, 28 /** 29 * List of Doclava error codes to treat as warnings. 30 * <p> 31 * See {@link com.google.doclava.Errors} for a complete list of error codes. 32 */ 33 val warnings: List<Int>, 34 /** 35 * List of Doclava error codes to ignore. 36 * <p> 37 * See {@link com.google.doclava.Errors} for a complete list of error codes. 38 */ 39 val hidden: List<Int>, 40 /** Message to display on check failure. */ 41 val onFailMessage: String? = null 42 ) : Serializable 43 44 private const val MSG_HIDE_API = 45 "If you are adding APIs that should be excluded from the public API surface,\n" + 46 "consider using package or private visibility. If the API must have public\n" + 47 "visibility, you may exclude it from public API by using the @hide javadoc\n" + 48 "annotation paired with the @RestrictTo(LIBRARY_GROUP) code annotation." 49 50 val CHECK_API_CONFIG_RELEASE = ChecksConfig( 51 onFailMessage = 52 "Compatibility with previously released public APIs has been broken. Please\n" + 53 "verify your change with Support API Council and provide error output,\n" + 54 "including the error messages and associated SHAs.\n" + 55 "\n" + 56 "If you are removing APIs, they must be deprecated first before being removed\n" + 57 "in a subsequent release.\n" + 58 "\n" + MSG_HIDE_API, 59 errors = (7..18).toList(), 60 warnings = emptyList(), 61 hidden = (2..6) + (19..30) 62 ) 63 64 // Check that the API we're building hasn't changed from the development 65 // version. These types of changes require an explicit API file update. 66 val CHECK_API_CONFIG_DEVELOP = ChecksConfig( 67 onFailMessage = 68 "Public API definition has changed. Please run ./gradlew updateApi to confirm\n" + 69 "these changes are intentional by updating the public API definition.\n" + 70 "\n" + MSG_HIDE_API, 71 errors = (2..30) - listOf(22), 72 warnings = emptyList(), 73 hidden = listOf(22) 74 ) 75 76 // This is a patch or finalized release. Check that the API we're building 77 // hasn't changed from the current. 78 val CHECK_API_CONFIG_PATCH = CHECK_API_CONFIG_DEVELOP.copy( 79 onFailMessage = "Public API definition may not change in finalized or patch releases.\n" + 80 "\n" + MSG_HIDE_API) 81