All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.errorprone.BugPattern Maven / Gradle / Ivy

The newest version!
/*
 * Copyright 2011 The Error Prone Authors.
 *
 * 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;

import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Annotation;
import java.lang.annotation.Retention;

/**
 * Describes a bug pattern detected by error-prone. Used to generate compiler error messages, for
 * {@code @}SuppressWarnings, and to generate the documentation that we host on our web site.
 *
 * @author [email protected] (Eddie Aftandilian)
 */
@Retention(RUNTIME)
public @interface BugPattern {

  /** A collection of standardized tags that can be applied to BugPatterns. */
  final class StandardTags {
    private StandardTags() {}

    /**
     * This check, for reasons of backwards compatibility or difficulty in cleaning up, should be
     * considered very likely to represent a real error in the vast majority ({@code >99.9%}) of
     * cases, but couldn't otherwise be turned on as an ERROR.
     *
     * 

Systems trying to determine the set of likely errors from a collection of BugPatterns * should act as if any BugPattern with {@link #severity()} of {@link SeverityLevel#ERROR} also * has this tag. */ public static final String LIKELY_ERROR = "LikelyError"; /** * This check detects a coding pattern that is valid within the Java language and doesn't * represent a runtime defect, but is otherwise discouraged for reasons of consistency within a * project or ease of understanding by other programmers. * *

Checks using this tag should limit their replacements to those that don't change the * behavior of the code (for example: adding clarifying parentheses, reordering modifiers in a * single declaration, removing implicit modifiers like {@code public} for members in an {@code * interface}). */ public static final String STYLE = "Style"; /** * This check detects a potential performance issue, where an easily-identifiable replacement * for the code being made will always result in a net positive performance improvement. */ public static final String PERFORMANCE = "Performance"; /** * This check detects code that may technically be working within a limited domain, but is * fragile, or violates generally-accepted assumptions of behavior. * *

Examples: DefaultCharset, where code implicitly uses the JVM default charset, will work in * circumstances where data being fed to the system happens to be compatible with the Charset, * but breaks down if fed data outside. */ public static final String FRAGILE_CODE = "FragileCode"; /** * This check points out potential issues when operating in a concurrent context * *

The code may work fine when accessed by 1 thread at a time, but may have some unintended * behavior when running in multiple threads. */ public static final String CONCURRENCY = "Concurrency"; /** * This check points out a coding pattern that, while functional, has an easier-to-read or * faster alternative. */ public static final String SIMPLIFICATION = "Simplification"; /** This check performs a refactoring, for example migrating to a new version of an API. */ public static final String REFACTORING = "Refactoring"; } /** * A unique identifier for this bug, used for @SuppressWarnings and in the compiler error message. * *

If this is not specified (or specified as an empty string), the class name of the check will * be used instead. */ String name() default ""; /** Alternate identifiers for this bug, which may also be used in @SuppressWarnings. */ String[] altNames() default {}; /** The type of link to generate in the compiler error message. */ LinkType linkType() default LinkType.AUTOGENERATED; /** The link URL to use if linkType() is LinkType.CUSTOM. */ String link() default ""; /** The type of link to generate in the compiler error message. */ enum LinkType { /** Link to autogenerated documentation, hosted on the error-prone web site. */ AUTOGENERATED, /** Custom string. */ CUSTOM, /** No link should be displayed. */ NONE } /** * A list of Stringly-typed tags to apply to this check. These tags can be consumed by tools * aggregating Error Prone checks (for example: a git pre-commit hook could clean up Java source * by finding any checks tagged "Style", run an Error Prone compile over the code with those * checks enabled, collect the fixes suggested and apply them). * *

To allow for sharing of tags across systems, a number of standard tags are available as * static constants in {@link StandardTags}. It is strongly encouraged to extract any custom tags * used in annotation property to constants that are shared by your codebase. */ String[] tags() default {}; /** * A short summary of the problem that this checker detects. Used for the default compiler error * message and for the short description in the generated docs. Should not end with a period, to * match javac warning/error style. * *

Markdown syntax is not allowed for this element. */ String summary(); /** * A longer explanation of the problem that this checker detects. Used as the main content in the * generated documentation for this checker. * *

Markdown syntax is allowed for this element. */ String explanation() default ""; SeverityLevel severity(); /** The severity of the diagnostic. */ enum SeverityLevel { ERROR, WARNING, /** Note that this level generally disables the bug checker. */ SUGGESTION, } /** True if the check can be disabled using command-line flags. */ boolean disableable() default true; /** * A set of annotation types that can be used to suppress the check. * *

Includes only {@link SuppressWarnings} by default. * *

To make a check unsuppressible, set {@code suppressionAnnotations} to empty. Note that * unsuppressible checks may still be disabled using command line flags (see {@link * #disableable}). */ Class[] suppressionAnnotations() default SuppressWarnings.class; /** * Generate an explanation of how to suppress the check. * *

This should only be disabled if the check has a non-standard suppression mechanism that * requires additional explanation. For example, {@link SuppressWarnings} cannot be applied to * packages, so checks that operate at the package level need special treatment. */ boolean documentSuppression() default true; /** * @deprecated this is a no-op that will be removed in the future */ @Deprecated boolean generateExamplesFromTestCases() default true; }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy