Skip to content

Commit 226f779

Browse files
tnorbyetnorbye
committed
Update lint documentation snapshot
Updates the issue documentation (which for example adds recently added lint checks and updates all the source URLs to reflect the current branch name).
1 parent 4ff2f4d commit 226f779

File tree

429 files changed

+3348
-1480
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

429 files changed

+3348
-1480
lines changed

‎docs/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,4 @@ snippets) but are readable and editable as markdown.)
99
Let's go there right now: [Link](README.md.html)
1010

1111
A (usually recent) snapshot of these docs are hosted
12-
[here](http://googlesamples.github.io/android-custom-lint-rules/).
12+
[here](https://googlesamples.github.io/android-custom-lint-rules/).

‎docs/README.md.html

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,10 @@
5252
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5353

5454
Documentation History:
55+
* November 2021: Added documentation for [option
56+
handling](api-guide/options.md.html)
5557
* September 2021: Added documentation for [annotation
56-
handling](annotations.md.html)
58+
handling](api-guide/annotations.md.html)
5759
* July 2021: Added documentation for
5860
[test modes](api-guide/test-modes.md.html)
5961
* June 2021: Added documentation for the

‎docs/api-guide.md.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
(insert api-guide/partial-analysis.md.html here)
1616
(insert api-guide/dataflow-analyzer.md.html here)
1717
(insert api-guide/annotations.md.html here)
18+
(insert api-guide/options.md.html here)
1819
(insert api-guide/faq.md.html here)
1920

2021
# Appendix: Recent Changes

‎docs/api-guide/changes.md.html

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,36 @@
55
information about user visible changes to lint, see the User
66
Guide.
77

8+
**7.3**
9+
10+
* The new AnnotationUsageType.DEFINTION now lets detectors easily check
11+
occurrences of an annotation in the source code. Previously,
12+
`visitAnnotationUsage` would only check annotated elements, not the
13+
annotations themselves, and to check an annotation you'd need to
14+
create an `UElementHandler`. See the docs for the new enum constant
15+
for more details, and for an example of a detector that was converted
16+
from a handler to using this, see `IgnoreWithoutReasonDetector`.
17+
18+
* Lint unit tests can now include `package-info.java` files with
19+
annotations in source form (until now, this only worked if the files
20+
were provided as binary class files)
21+
22+
**7.2**
23+
24+
* There is now a way to register “options” for detectors. These are
25+
simple key/value pairs of type string, integer, boolean or file, and
26+
users can configure values in `lint.xml` files. This has all been
27+
possible since 4.2, but in 7.2 there is now a way to register the
28+
names, descriptions and default values of these options, and these
29+
will show up in issue explanations, HTML reports, and so on. (In the
30+
future we can use this to create an Options UI in the IDE, allow
31+
configuration via Gradle DSL, and so on.)
32+
33+
For more, see the [options chapter](options.md.html).
34+
35+
* A new test mode, `TestMode.CDATA`, checks that tests correctly handle
36+
XML CDATA sections in `<string>` declarations.
37+
838
**7.1**
939

1040
* Lint now bundles IntelliJ version 2021.1 and Kotlin compiler version 1.5.30.

‎docs/api-guide/options.md.html

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
<meta charset="utf-8" lang="kotlin">
2+
3+
# Options
4+
5+
## Usage
6+
7+
Users can configure lint using `lint.xml` files, turning on and off
8+
checks, changing the default severity, ignoring violations based on
9+
paths or regular expressions matching paths or messages, and so on.
10+
11+
They can also configure “options” on a per issue type basis. Options
12+
are simply strings, booleans, integers or paths that configure how a
13+
detector works.
14+
15+
For example, in the following `lint.xml` file, we're configuring the
16+
`UnknownNullness` detector to turn on its `ignoreDeprecated` option,
17+
and we're telling the `TooManyViews` detector that the maximum number
18+
of views in a layout it should allow before generating a warning should
19+
be set to 20:
20+
21+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~xml
22+
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
23+
&lt;lint&gt;
24+
&lt;issue id="UnknownNullness"&gt;
25+
&lt;option name="ignoreDeprecated" value="true" /&gt;
26+
&lt;/issue&gt;
27+
&lt;issue id="TooManyViews"&gt;
28+
&lt;option name="maxCount" value="20" /&gt;
29+
&lt;/issue&gt;
30+
&lt;/lint&gt;
31+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32+
33+
Note that `lint.xml` files can be located not just in the project
34+
directory but nested as well, for example for a particular source
35+
folder.
36+
37+
(See the [lint.xml](../usage/lintxml.md.html) documentation for more.)
38+
39+
## Creating Options
40+
41+
First, create an `Option` and register it with the corresponding
42+
`Issue`.
43+
44+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin
45+
val MAX_COUNT = IntOption("maxCount", "Max number of views allowed", 80)
46+
val MY_ISSUE = Issue.create("MyId", ...)
47+
.setOptions(listOf(MAX_COUNT))
48+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
49+
50+
An option has a few pieces of metadata:
51+
52+
* The name, which is a short identifier. Users will configure the
53+
option by listing this key along with the configured value in their
54+
`lint.xml` files. By convention this should be using camel case and
55+
only valid Java identifier characters.
56+
57+
* A description. This should be a short sentence which lists the
58+
purpose of the option (and should be capitalized, and not end with
59+
punctuation).
60+
61+
* A default value. This is the value that will be returned from
62+
`Option.getValue()` if the user has not configured the setting.
63+
64+
* For integer and float options, minimum and maximum allowed values.
65+
66+
* An optional explanation. This is a longer explanation of the option,
67+
if necessary.
68+
69+
The name and default value are used by lint when options are looked up
70+
by detectors; the description, explanation and allowed ranges are used
71+
to include information about available options when lint generates for
72+
example HTML reports, or text reports including explanations, or
73+
displaying lint checks in the IDE settings panel, and so on.
74+
75+
There are currently 5 types of options: Strings, booleans, ints, floats
76+
and paths. There's a separate option class for each one, which makes it
77+
easier to look up these options since for example for a `StringOption`,
78+
`getValue` returns a `String`, for an `IntOption` it returns an `Int`,
79+
and so on.
80+
81+
Option Type | Option Class
82+
------------------------|-----------------------------------
83+
`String` | `StringOption`
84+
`Boolean` | `BooleanOption`
85+
`Int` | `IntOption`
86+
`Float` | `FloatOption`
87+
`File` | `FileOption`
88+
89+
## Reading Options
90+
91+
To look up the configured value for an option, just call `getValue`
92+
and pass in the `context`:
93+
94+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin
95+
val maxCount = MAX_COUNT.getValue(context)
96+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
97+
98+
This will return the `Int` value configured for this option by the
99+
user, or if not set, our original default value, in this case 80.
100+
101+
## Specific Configurations
102+
103+
The above call will look up the option configured for the specific
104+
source file in the current `context`, which might be an individual
105+
Kotlin source file. That's generally what you want; users can configure
106+
`lint.xml` files not just at the root of the project; they can be
107+
placed throughout the source folders and are interpreted by lint to
108+
apply to the folders below. Therefore, if we're analyzing a particular
109+
Kotlin file and we want to check an option, you generally want to check
110+
what's configured locally for this file.
111+
112+
However, there are cases where you want to look up options up front,
113+
for example at the project level.
114+
115+
In that case, first look up the particular configuration you want, and
116+
then pass in that configuration instead of the context to the
117+
`Option.getValue` call.
118+
119+
For example, the context for the current module is already available in
120+
the `context`, so you might for example look up the option value like
121+
this:
122+
123+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin
124+
val maxCount = MAX_COUNT.getValue(context.configuration)
125+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126+
127+
If you want to find the most applicable configuration for a given
128+
source file, use
129+
130+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin
131+
val configuration = context.findConfiguration(context.file)
132+
val maxCount = MAX_COUNT.getValue(configuration)
133+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
134+
135+
## Files
136+
137+
Note that there is a special `Option` type for files and paths:
138+
`FileOption`. Make sure that you use this instead of just a
139+
`StringOption` if you are planning on configuring files, because in the
140+
case of paths, users will want to specify paths relative to the
141+
location of the `lint.xml` file where the path is defined. For
142+
`FileOption` lint is aware of this and will convert the relative path
143+
string as necessary.
144+
145+
## Constraints
146+
147+
Note that the integer and float options allow you to specify a valid
148+
range for the configured value -- a minimum (inclusive) and a maximum
149+
(exclusive):
150+
151+
This range will be included with the option documentation, such as in
152+
“**duration** (default is 1.5): Expected duration in seconds. Must be
153+
at least 0.0 and less than 15.0.”
154+
155+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin
156+
private val DURATION_OPTION = FloatOption(
157+
name = "duration",
158+
description = "Expected duration",
159+
defaultValue = 1.5f,
160+
min = 0f,
161+
max = 15f
162+
)
163+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
164+
165+
It will also be checked at runtime, and if the configured value is
166+
outside of the range, lint will report an error and pinpoint the
167+
location in the invalid `lint.xml` file:
168+
169+
```text
170+
lint.xml:4: Error: duration: Must be less than 15.0 [LintError]
171+
<option name="duration" value="100.0" />
172+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
173+
1 errors, 0 warnings
174+
```
175+
176+
## Testing Options
177+
178+
When writing a lint unit test, you can easily configure specific values
179+
for your detector options. On the `lint()` test task, you can call
180+
`configureOption(option, value)`. There are a number of overloads for
181+
this method, so you can reference the option by its string name, or
182+
passing in the option instance, and if you do, you can pass in strings,
183+
integers, booleans, floats and files as values. Here's an example:
184+
185+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin
186+
lint().files(
187+
kotlin("fun test() { println("Hello World.") }")
188+
)
189+
.configureOption(MAX_COUNT, 150)
190+
.run()
191+
.expectClean()
192+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
193+
194+
## Supporting Lint 4.2, 7.0 and 7.1
195+
196+
The `Option` support is new in 7.2. If your lint check still needs to
197+
work with older versions of lint, you can bypass the option
198+
registration, and just read option values directly from the
199+
configuration.
200+
201+
First, find the configuration as shown above, and then instead of
202+
calling `Option.getValue`, call `getOption` on the configuration:
203+
204+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin
205+
val option: String? = configuration.getOption(ISSUE, "maxCount")
206+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
207+
208+
The `getOption` method returns a `String`. For numbers and booleans,
209+
the coniguration also provides lookups which will convert the value to
210+
a number or boolean respectively: `getOptionAsInt`,
211+
`getOptionAsBoolean`, and most importantly, `getOptionAsFile`. If you
212+
are looking up paths, be sure to use `getOptionAsFile` since it has the
213+
important attribute that it allows paths to be relative to the
214+
configuration file where the (possibly inherited) value was defined,
215+
which is what users expect when editing `lint.xml` files.
216+
217+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin
218+
val option = configuration.getOptionAsInt(ISSUE, "maxCount", 100)
219+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
220+
221+
<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="markdeep.min.js" charset="utf-8"></script><script src="https://morgan3d.github.io/markdeep/latest/markdeep.min.js" charset="utf-8"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

‎docs/api-guide/test-modes.md.html

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -484,4 +484,37 @@
484484
.build();
485485
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
486486

487+
### CDATA Mode
488+
489+
When declaring string resources, you may want to use XML CDATA sections
490+
instead of plain text. For example, instead of
491+
492+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~xml
493+
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
494+
&lt;resources&gt;
495+
&lt;string name="app_name"&gt;Application Name&lt;/string&gt;
496+
&lt;/resources&gt;
497+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
498+
499+
you can equivalently use
500+
501+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~xml
502+
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
503+
&lt;resources&gt;
504+
&lt;string name="app_name"&gt;&lt;![CDATA[Application Name]]&gt;&lt;/string&gt;
505+
&lt;/resources&gt;
506+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
507+
508+
(where you can place newlines and other unescaped text inside the bracketed span.)
509+
510+
This alternative form shows up differently in the XML DOM that is
511+
provided to lint detectors; in particular, if you are iterating through
512+
the `Node` children of an `Element`, you should not just look at nodes
513+
with `nodeType == Node.TEXT_NODE`; you need to also handle `noteType ==
514+
Node.CDATA_SECTION_NODE`.
515+
516+
This test mode will automatically retry all your tests that define
517+
string resources, and will convert regular text into `CDATA` and makes
518+
sure the results continue to be the same.
519+
487520
<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="markdeep.min.js" charset="utf-8"></script><script src="https://morgan3d.github.io/markdeep/latest/markdeep.min.js" charset="utf-8"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

‎docs/checks/AaptCrash.md.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,9 @@
2525
Editing
2626
: This check runs on the fly in the IDE editor
2727
Implementation
28-
: [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-checks/src/main/java/com/android/tools/lint/checks/ResourceCycleDetector.kt)
28+
: [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-checks/src/main/java/com/android/tools/lint/checks/ResourceCycleDetector.kt)
2929
Tests
30-
: [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/ResourceCycleDetectorTest.java)
30+
: [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/ResourceCycleDetectorTest.java)
3131
Copyright Year
3232
: 2014
3333

@@ -68,7 +68,7 @@
6868
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6969

7070
You can also visit the
71-
[source code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/ResourceCycleDetectorTest.java)
71+
[source code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/ResourceCycleDetectorTest.java)
7272
for the unit tests for this check to see additional scenarios.
7373

7474
The above example was automatically extracted from the first unit test

‎docs/checks/AcceptsUserCertificates.md.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,9 @@
2525
See
2626
: https://developer.android.com/training/articles/security-config#TrustingDebugCa
2727
Implementation
28-
: [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-checks/src/main/java/com/android/tools/lint/checks/NetworkSecurityConfigDetector.java)
28+
: [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-checks/src/main/java/com/android/tools/lint/checks/NetworkSecurityConfigDetector.java)
2929
Tests
30-
: [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/NetworkSecurityConfigDetectorTest.java)
30+
: [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/NetworkSecurityConfigDetectorTest.java)
3131
Copyright Year
3232
: 2016
3333

@@ -67,7 +67,7 @@
6767
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6868

6969
You can also visit the
70-
[source code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/NetworkSecurityConfigDetectorTest.java)
70+
[source code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/NetworkSecurityConfigDetectorTest.java)
7171
for the unit tests for this check to see additional scenarios.
7272

7373
The above example was automatically extracted from the first unit test

‎docs/checks/AccidentalOctal.md.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@
2323
Editing
2424
: This check runs on the fly in the IDE editor
2525
Implementation
26-
: [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-checks/src/main/java/com/android/tools/lint/checks/GradleDetector.kt)
26+
: [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-checks/src/main/java/com/android/tools/lint/checks/GradleDetector.kt)
2727
Tests
28-
: [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/GradleDetectorTest.kt)
28+
: [Source Code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/GradleDetectorTest.kt)
2929
Copyright Year
3030
: 2014
3131

@@ -72,7 +72,7 @@
7272
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7373

7474
You can also visit the
75-
[source code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-master-dev:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/GradleDetectorTest.kt)
75+
[source code](https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:lint/libs/lint-tests/src/test/java/com/android/tools/lint/checks/GradleDetectorTest.kt)
7676
for the unit tests for this check to see additional scenarios.
7777

7878
The above example was automatically extracted from the first unit test

0 commit comments

Comments
 (0)