/*
 * Copyright 2016 Google Inc. All Rights Reserved.
 *
 * 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 com.google.errorprone.annotations;

import java.lang.annotation.Annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

//TODO(bangert): Allow restricting entire classes.
/**
 * Restrict this method to callsites with a whitelist annotation.
 *
 * <p>Callers that are not whitelisted will cause a configurable compiler diagnostic. Whitelisting
 * can either allow the call outright, or make the compiler emit a warning when the API is called.
 * Paths matching a regular expression, e.g. unit tests, can also be excluded.
 *
 * <p>The following example shows a hypothetical, potentially unsafe {@code Foo.bar} method. It is
 * marked with the {@code @RestrictedApi} annotations such that callers annotated with
 * {@code @LegacyFooBar} raise a warning, whereas the {@code @ReviewedFooBar} annotation silently
 * allows the call.
 *
 * <p>The {@code @LegacyFooBar} annotation can be used to allow existing call sites until they are
 * refactored, while prohibiting new call-sites. Call-sites determined to be acceptable, for example
 * through code review, could be marked {@code @ReviewedFooBar}.
 *
 * <pre>{@code
 * public {@literal @}interface LegacyUnsafeFooBar{}
 *
 * public {@literal @}interface ReviewedFooBar{
 *  public string reviewer();
 *  public string comments();
 * }
 *
 * public class Foo {
 *   {@literal @}RestrictedApi(
 *      explanation="You could shoot yourself in the foot with Foo.bar if you aren't careful",
 *      link="http://edsger.dijkstra/foo_bar_consider_harmful.html",
 *      allowedOnPath="testsuite/.*", // Unsafe behavior in tests is ok.
 *      whitelistAnnotations = {ReviewedFooBar.class},
 *      whitelistWithWarningAnnotations = {LegacyFooBar.class})
 *   public void bar() {
 *      if (complicatedCondition) {
 *          shoot_your_foot();
 *      } else {
 *          solve_your_problem();
 *      }
 *   }
 *   boolean complicatedCondition = true;
 *
 *   {@literal @}ReviewedFooBar(
 *      reviewer="bangert",
 *      comments="Makes sure complicatedCondition isn't true, so bar is safe!"
 *   )
 *   public void safeBar() {
 *      if (!complicatedCondition) {
 *          bar();
 *      }
 *   }
 *
 *   {@literal @}LegacyUnsafeFooBar
 *   public void someOldCode() {
 *      // ...
 *      bar()
 *      // ...
 *   }
 * }
 * }</pre>
 */
@Target({ElementType.CONSTRUCTOR, ElementType.METHOD})
public @interface RestrictedApi {
  /** Very short name for the diagnostic message. Used in error-prone. */
  public String checkerName() default "RestrictedApi";

  /** Explanation why the API is restricted, to be inserted into the compiler output. */
  public String explanation();

  /** Link explaining why the API is restricted */
  public String link();

  /**
   * Allow the restricted API on paths matching this regular expression.
   *
   * <p>Leave empty (the default) to enforce the API restrictions on all paths.
   */
  public String allowedOnPath() default "";

  /** Allow calls to the restricted API in methods or classes with this annotation. */
  public Class<? extends Annotation>[] whitelistAnnotations() default {};

  /**
   * Emit warnings, not errors, on calls to the restricted API for callers with this annotation.
   *
   * <p>This should only be used if callers should aggressively move away from this API (or change
   * to a whitelist annotation after review). Too many warnings will lead to ALL warnings being
   * ignored, so tread very carefully.
   */
  public Class<? extends Annotation>[] whitelistWithWarningAnnotations() default {};
}

@@ -774,16 +774,17 @@
 get;%0A%0A//
+ 
 TODO(ban
@@ -1372,32 +1372,38 @@
 * %7B@code @Legacy
+Unsafe
 FooBar%7D raise a 
@@ -1457,16 +1457,19 @@
 notation
+%0A *
  silentl
@@ -1469,19 +1469,16 @@
 silently
-%0A *
  allows 
@@ -1510,24 +1510,30 @@
 code @Legacy
+Unsafe
 FooBar%7D anno
@@ -1594,15 +1594,15 @@
 they
+%0A *
  are
-%0A *
  ref
@@ -1687,24 +1687,27 @@
 ble, for
+%0A *
  example
 %0A * thro
@@ -1698,19 +1698,16 @@
  example
-%0A *
  through
@@ -2346,16 +2346,22 @@
  %7BLegacy
+Unsafe
 FooBar.c

Fix typo