Skip to content

Commit f3c96a6

Browse files
tnorbyetnorbye
authored
Merge pull request googlesamples#67 from tnorbye/snapshot11
Update lint documentation snapshot
2 parents 4ff2f4d + 226f779 commit f3c96a6

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)