com.android.tools.lint.detector.api
Class Issue

java.lang.Object
  com.android.tools.lint.detector.api.Issue

All Implemented Interfaces:

java.lang.Comparable<Issue>

@Beta
public final class Issue
extends java.lang.Object
implements java.lang.Comparable<Issue>

An issue is a potential bug in an Android application. An issue is discovered by a Detector, and has an associated Severity.

Issues and detectors are separate classes because a detector can discover multiple different issues as it's analyzing code, and we want to be able to different severities for different issues, the ability to suppress one but not other issues from the same detector, and so on.

NOTE: This is not a public or final API; if you rely on this be prepared to adjust your code for the next tools release.

Nested Class Summary

static class

Issue.OutputFormat The format of output from the description methods

Method Summary

Issue	addMoreInfo(java.lang.String moreInfoUrl) Adds a more info URL string
int	compareTo(Issue other) Sorts the detectors alphabetically by id.
static java.lang.String	convertMarkup(java.lang.String text, boolean html) Converts the given markup text to HTML or text, depending on the.
static Issue	create(java.lang.String id, java.lang.String briefDescription, java.lang.String description, java.lang.String explanation, Category category, int priority, Severity severity, Implementation implementation) Creates a new issue.
java.lang.String	getBriefDescription(Issue.OutputFormat format) Briefly (in a couple of words) describes these errors
Category	getCategory() The primary category of the issue
Severity	getDefaultSeverity() Returns the default severity of the issues found by this detector (some tools may allow the user to specify custom severities for detectors).
java.lang.String	getDescription(Issue.OutputFormat format) Describes in a single line the kinds of checks performed by this rule
java.lang.String	getExplanation(Issue.OutputFormat format) Describes the error found by this rule, e.g.
java.lang.String	getId() Returns the unique id of this issue.
Implementation	getImplementation() Returns the implementation for the given issue
java.util.List<java.lang.String>	getMoreInfo() Returns a link (a URL string) to more information, or null
int	getPriority() Returns a priority, in the range 1-10, with 10 being the most severe and 1 the least
boolean	isEnabledByDefault() Returns whether this issue should be enabled by default, unless the user has explicitly disabled it.
Issue	setEnabledByDefault(boolean enabledByDefault) Sets whether this issue is enabled by default.
void	setImplementation(Implementation implementation) Sets the implementation for the given issue.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

create

@NonNull
public static Issue create(@NonNull
                                   java.lang.String id,
                                   @NonNull
                                   java.lang.String briefDescription,
                                   @NonNull
                                   java.lang.String description,
                                   @NonNull
                                   java.lang.String explanation,
                                   @NonNull
                                   Category category,
                                   int priority,
                                   @NonNull
                                   Severity severity,
                                   @NonNull
                                   Implementation implementation)

Creates a new issue. The description strings can use some simple markup; see the convertMarkup(String, boolean) method for details.

Parameters:

id - the fixed id of the issue

briefDescription - short summary (typically 5-6 words or less), typically describing the problem rather than the fix (e.g. "Missing minSdkVersion")

description - the quick summary of the issue (one line), typically describing what the detector looks for

explanation - a full explanation of the issue, with suggestions for how to fix it

category - the associated category, if any

priority - the priority, a number from 1 to 10 with 10 being most important/severe

severity - the default severity of the issue

implementation - the default implementation for this issue

Returns:

a new Issue

getId

@NonNull
public java.lang.String getId()

Returns the unique id of this issue. These should not change over time since they are used to persist the names of issues suppressed by the user etc. It is typically a single camel-cased word.

Returns:

the associated fixed id, never null and always unique

getBriefDescription

@NonNull
public java.lang.String getBriefDescription(@NonNull
                                                    Issue.OutputFormat format)

Briefly (in a couple of words) describes these errors

Returns:

a brief summary of the issue, never null, never empty

See Also:

getDescription(OutputFormat)

getDescription

@NonNull
public java.lang.String getDescription(@NonNull
                                               Issue.OutputFormat format)

Describes in a single line the kinds of checks performed by this rule

Returns:

a quick summary of the issue, never null, never empty

See Also:

getBriefDescription(OutputFormat)

getExplanation

@NonNull
public java.lang.String getExplanation(@NonNull
                                               Issue.OutputFormat format)

Describes the error found by this rule, e.g. "Buttons must define contentDescriptions". Preferably the explanation should also contain a description of how the problem should be solved. Additional info can be provided via getMoreInfo().

Parameters:

format - the format to write the format as

Returns:

an explanation of the issue, never null, never empty

getCategory

@NonNull
public Category getCategory()

The primary category of the issue

Returns:

the primary category of the issue, never null

getPriority

public int getPriority()

Returns a priority, in the range 1-10, with 10 being the most severe and 1 the least

Returns:

a priority from 1 to 10

getDefaultSeverity

@NonNull
public Severity getDefaultSeverity()

Returns the default severity of the issues found by this detector (some tools may allow the user to specify custom severities for detectors).

Note that even though the normal way for an issue to be disabled is for the Configuration to return Severity.IGNORE, there is a isEnabledByDefault() method which can be used to turn off issues by default. This is done rather than just having the severity as the only attribute on the issue such that an issue can be configured with an appropriate severity (such as Severity.ERROR) even when issues are disabled by default for example because they are experimental or not yet stable.

Returns:

the severity of the issues found by this detector

getMoreInfo

@NonNull
public java.util.List<java.lang.String> getMoreInfo()

Returns a link (a URL string) to more information, or null

Returns:

a link to more information, or null

addMoreInfo

@NonNull
public Issue addMoreInfo(@NonNull
                                 java.lang.String moreInfoUrl)

Adds a more info URL string

Parameters:

moreInfoUrl - url string

Returns:

this, for constructor chaining

isEnabledByDefault

public boolean isEnabledByDefault()

Returns whether this issue should be enabled by default, unless the user has explicitly disabled it.

Returns:

true if this issue should be enabled by default

getImplementation

@NonNull
public Implementation getImplementation()

Returns the implementation for the given issue

Returns:

the implementation for this issue

setImplementation

public void setImplementation(@NonNull
                              Implementation implementation)

Sets the implementation for the given issue. This is typically done by IDEs that can offer a replacement for a given issue which performs better or in some other way works better within the IDE.

Parameters:

implementation - the new implementation to use

compareTo

public int compareTo(Issue other)

Sorts the detectors alphabetically by id. This is intended to make it convenient to store settings for detectors in a fixed order. It is not intended as the order to be shown to the user; for that, a tool embedding lint might consider the priorities, categories, severities etc of the various detectors.

Specified by:

compareTo in interface java.lang.Comparable<Issue>

Parameters:

other - the Issue to compare this issue to

setEnabledByDefault

@NonNull
public Issue setEnabledByDefault(boolean enabledByDefault)

Sets whether this issue is enabled by default.

Parameters:

enabledByDefault - whether the issue should be enabled by default

Returns:

this, for constructor chaining

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

convertMarkup

@NonNull
public static java.lang.String convertMarkup(@NonNull
                                                     java.lang.String text,
                                                     boolean html)

Converts the given markup text to HTML or text, depending on the.

This will recognize the following formatting conventions:

• HTTP urls (http://...)
• Sentences immediately surrounded by * will be shown as bold.
• Sentences immediately surrounded by ` will be shown using monospace fonts

Furthermore, newlines are converted to br's when converting newlines. Note: It does not insert <html> tags around the fragment for HTML output.

TODO: Consider switching to the restructured text format - http://docutils.sourceforge.net/docs/user/rst/quickstart.html

Parameters:

text - the text to be formatted

html - whether to convert into HTML or text

Returns:

the corresponding HTML or text properly formatted