/*
 * Copyright 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.car.app.annotations;

import androidx.car.app.CarContext;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Defines the minimum API level required to be able to use this model, field or method.
 * <p>
 * Before using any of this elements, application must check that
 * {@link CarContext#getCarAppApiLevel()} is equal or greater than the value of this annotation.
 * <p>
 * For example, if an application wants to use a newer template "Foo" marked with
 * <code>@RequiresHostApiLevel(2)</code> while maintain backwards compatibility with older hosts
 * by using an older template "Bar" (<code>@RequiresHostApiLevel(1)</code>), they can do:
 *
 * <pre>
 * if (getCarContext().getCarApiLevel() >= 2) {
 *     // Use new feature
 *     return Foo.Builder()....;
 * } else {
 *     // Use supported fallback
 *     return Bar.Builder()....;
 * }
 * </pre>
 *
 * If a certain model or method has no {@link RequiresCarApi} annotation, it is assumed to
 * be available in all car API levels.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.METHOD})
public @interface RequiresCarApi {

    /**
     * The minimum API level required to be able to use this model, field or method. Applications
     * shouldn't use any elements annotated with a {@link RequiresCarApi} greater than
     * {@link CarContext#getCarAppApiLevel()}
     */
    int value();
}

@@ -921,32 +921,33 @@
 his model, field
+,
  or method.%0A * %3C
@@ -942,26 +942,25 @@
 method.%0A
+ *%0A
  * %3Cp%3E
-%0A * 
 Before u
@@ -973,18 +973,19 @@
 ny of th
-is
+ese
  element
@@ -1118,16 +1118,15 @@
 .%0A *
- %3Cp%3E
 %0A * 
+%3Cp%3E
 For 
@@ -1218,28 +1218,22 @@
 Requires
-HostApiLevel
+CarApi
 (2)%3C/cod
@@ -1687,16 +1687,16 @@
 umed to%0A
-
  * be av
@@ -1726,16 +1726,530 @@
 levels.%0A
+ *%0A * %3Ch4%3EAPI stability%3C/h4%3E%0A *%0A * New APIs that are introduced during alpha library releases should be used with extra caution.%0A * Specifically, apps should NOT use APIs in the following categories in their production APKs:%0A *%0A * %3Cul%3E%0A *   %3Cli%3ENew APIs that are only available in alpha releases%0A *   %3Cli%3EAPIs that are annotated with %7B@link ExperimentalCarApi%7D%0A * %3C/ul%3E%0A *%0A * %3Cp%3EAs they are considered unstable or experimental, these APIs may change and potentially break%0A * your app when the host(s) are updated.%0A
  */%0A@Ret

Add an API stability section in the RequiresCarApi's class javadoc