Home | History | Annotate | Download | only in doclava 
      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