sdk/sources/android-25/android/annotation/CheckResult.java

   1 /*
   2  * Copyright (C) 2015 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 package android.annotation;
  17
  18 import java.lang.annotation.Retention;
  19 import java.lang.annotation.Target;
  20
  21 import static java.lang.annotation.ElementType.METHOD;
  22 import static java.lang.annotation.RetentionPolicy.SOURCE;
  23
  24 /**
  25  * Denotes that the annotated method returns a result that it typically is
  26  * an error to ignore. This is usually used for methods that have no side effect,
  27  * so calling it without actually looking at the result usually means the developer
  28  * has misunderstood what the method does.
  29  * <p>
  30  * Example:
  31  * <pre>{@code
  32  *  public @CheckResult String trim(String s) { return s.trim(); }
  33  *  ...
  34  *  s.trim(); // this is probably an error
  35  *  s = s.trim(); // ok
  36  * }</pre>
  37  *
  38  * @hide
  39  */
  40 @Retention(SOURCE)
  41 @Target({METHOD})
  42 public @interface CheckResult {
  43     /** Defines the name of the suggested method to use instead, if applicable (using
  44      * the same signature format as javadoc.) If there is more than one possibility,
  45      * list them all separated by commas.
  46      * <p>
  47      * For example, ProcessBuilder has a method named {@code redirectErrorStream()}
  48      * which sounds like it might redirect the error stream. It does not. It's just
  49      * a getter which returns whether the process builder will redirect the error stream,
  50      * and to actually set it, you must call {@code redirectErrorStream(boolean)}.
  51      * In that case, the method should be defined like this:
  52      * <pre>
  53      *  &#64;CheckResult(suggest="#redirectErrorStream(boolean)")
  54      *  public boolean redirectErrorStream() { ... }
  55      * </pre>
  56      */
  57     String suggest() default "";
  58 }