Skip to content

Commit fa4765f

Browse files
tnorbyetnorbye
committed
Update documentation snapshot
1 parent d63e0e8 commit fa4765f

27 files changed

+363
-245
lines changed

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,9 @@
3131

3232
### API Stability
3333

34-
Lint's APIs are still marked as @Beta, and we have made it very clear
35-
all along that this is not a stable API, so custom lint checks may need
36-
to be updated periodically to keep working.
34+
Lint's APIs are not stable, and a large part of Lint's API surface is
35+
not under our control (such as UAST and PSI). Therefore, custom lint
36+
checks may need to be updated periodically to keep working.
3737

3838
However, ”some APIs are more stable than others“. In particular, the
3939
detector API (described below) is much less likely to change than the

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,15 @@
1919
annotations in source form (until now, this only worked if the files
2020
were provided as binary class files)
2121

22+
* String replacement quickfixes can now be configured with a list of
23+
imports to be performed when the fix is applied. This can be used to
24+
for example import Kotlin extension functions needed by the
25+
replacement string. (You should not use this for normal imports;
26+
instead, the replacement string should use fully qualified names
27+
everywhere along with the `shortenNames` property on the fix, and
28+
then lint will rewrite and import all symbols that can be done
29+
without conflicts.)
30+
2231
**7.2**
2332

2433
* There is now a way to register “options” for detectors. These are

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,21 @@
129129
with simple names because there is a conflicting import of the same
130130
name from a different package.
131131

132+
Normally, you should write your replacement source code using fully
133+
qualified names, and then apply `shortenNames` to the quickfix to
134+
tell lint to replace fully qualified names with imports; don't try
135+
to write your quickfix to also add the import statements on its
136+
own. There's a possibility that a given name cannot be imported
137+
because it's already importing the same name for a different
138+
namespace. When using fully qualified names, lint will specifically
139+
handle this.
140+
141+
In some cases you cannot use fully qualified names in the code
142+
snippet; this is the case with Kotlin extension functions for
143+
example. For that scenario, the replacement quickfix has an
144+
`imports` property you can use to specify methods (and classes and
145+
fields) to import at the same time.
146+
132147
* `fix().annotate`: Annotating an element. This will add (or optionally
133148
replace) an annotation on a source element such as a method. It will
134149
also handle import management.

‎docs/checks/BadConfigurationProvider.md.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@
1717
Platform
1818
: Android
1919
Vendor
20-
: Android Open Source Project (androidx.work.lint.workmanager)
20+
: Android Open Source Project
2121
Identifier
22-
: androidx.work.lint.workmanager
22+
: androidx.work
2323
Feedback
24-
: https://issuetracker.google.com/issues/new?component=192731
24+
: https://issuetracker.google.com/issues/new?component=409906
2525
Affects
2626
: Kotlin and Java files
2727
Editing

‎docs/checks/BadPeriodicWorkRequestEnqueue.md.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,11 @@
1515
Platform
1616
: Android
1717
Vendor
18-
: Android Open Source Project (androidx.work.lint.workmanager)
18+
: Android Open Source Project
1919
Identifier
20-
: androidx.work.lint.workmanager
20+
: androidx.work
2121
Feedback
22-
: https://issuetracker.google.com/issues/new?component=192731
22+
: https://issuetracker.google.com/issues/new?component=409906
2323
Affects
2424
: Kotlin and Java files
2525
Editing

‎docs/checks/EnsureInitializerMetadata.md.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@
1717
Platform
1818
: Android
1919
Vendor
20-
: Android Open Source Project (androidx.startup.lint.startupruntime)
20+
: Android Open Source Project
2121
Identifier
22-
: androidx.startup.lint.startupruntime
22+
: androidx.startup
2323
Feedback
24-
: https://issuetracker.google.com/issues/new?component=192731
24+
: https://issuetracker.google.com/issues/new?component=823348
2525
Affects
2626
: Kotlin and Java files and manifest files
2727
Editing

‎docs/checks/EnsureInitializerNoArgConstr.md.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@
1717
Platform
1818
: Android
1919
Vendor
20-
: Android Open Source Project (androidx.startup.lint.startupruntime)
20+
: Android Open Source Project
2121
Identifier
22-
: androidx.startup.lint.startupruntime
22+
: androidx.startup
2323
Feedback
24-
: https://issuetracker.google.com/issues/new?component=192731
24+
: https://issuetracker.google.com/issues/new?component=823348
2525
Affects
2626
: Kotlin and Java files
2727
Editing

‎docs/checks/FragmentGradleConfiguration.md.html

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,11 @@
1515
Platform
1616
: Android
1717
Vendor
18-
: Android Open Source Project (androidx.fragment.testing.lint.fragmenttesting)
18+
: Android Open Source Project
1919
Identifier
20-
: androidx.fragment.testing.lint.fragmenttesting
20+
: androidx.fragment.testing
2121
Feedback
22-
: https://issuetracker.google.com/issues/new?component=192731
22+
: https://issuetracker.google.com/issues/new?component=460964
2323
Affects
2424
: Gradle build files
2525
Editing
@@ -68,7 +68,7 @@
6868
The above example was automatically extracted from the first unit test
6969
found for this lint check, `GradleConfigurationDetector.expectFail`.
7070
To report a problem with this extracted sample, visit
71-
https://issuetracker.google.com/issues/new?component=192731.
71+
https://issuetracker.google.com/issues/new?component=460964.
7272

7373
(##) Suppressing
7474

‎docs/checks/IdleBatteryChargingConstraints.md.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,11 @@
1515
Platform
1616
: Android
1717
Vendor
18-
: Android Open Source Project (androidx.work.lint.workmanager)
18+
: Android Open Source Project
1919
Identifier
20-
: androidx.work.lint.workmanager
20+
: androidx.work
2121
Feedback
22-
: https://issuetracker.google.com/issues/new?component=192731
22+
: https://issuetracker.google.com/issues/new?component=409906
2323
Affects
2424
: Kotlin and Java files
2525
Editing

‎docs/checks/InvalidPeriodicWorkRequestInterval.md.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@
1717
Platform
1818
: Android
1919
Vendor
20-
: Android Open Source Project (androidx.work.lint.workmanager)
20+
: Android Open Source Project
2121
Identifier
22-
: androidx.work.lint.workmanager
22+
: androidx.work
2323
Feedback
24-
: https://issuetracker.google.com/issues/new?component=192731
24+
: https://issuetracker.google.com/issues/new?component=409906
2525
Affects
2626
: Kotlin and Java files
2727
Editing

‎docs/checks/KotlinNullnessAnnotation.md.html

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
<meta charset="utf-8">
2+
(#) Kotlin nullability annotation
3+
4+
!!! ERROR: Kotlin nullability annotation
5+
This is an error.
6+
7+
Id
8+
: `KotlinNullnessAnnotation`
9+
Summary
10+
: Kotlin nullability annotation
11+
Severity
12+
: Error
13+
Category
14+
: Correctness
15+
Platform
16+
: Android
17+
Vendor
18+
: Android Open Source Project
19+
Feedback
20+
: https://issuetracker.google.com/issues/new?component=192708
21+
Affects
22+
: Kotlin and Java files
23+
Editing
24+
: This check runs on the fly in the IDE editor
25+
Implementation
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/KotlinNullnessAnnotationDetector.kt)
27+
Tests
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/KotlinNullnessAnnotationDetectorTest.kt)
29+
Copyright Year
30+
: 2022
31+
32+
In Kotlin, nullness is part of the type system; `s: String` is **never**
33+
null and `s: String?` is sometimes null, whether or not you add in
34+
additional annotations stating `@NonNull` or `@Nullable`. These are
35+
likely copy/paste mistakes, and are misleading.
36+
37+
!!! Tip
38+
This lint check has an associated quickfix available in the IDE.
39+
40+
(##) Example
41+
42+
Here is an example of lint warnings produced by this check:
43+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~text
44+
src/test/pkg/test.kt:7:Warning: Do not use @NonNull in Kotlin; the
45+
nullability is already implied by the Kotlin type String not ending with
46+
? [KotlinNullnessAnnotation]
47+
48+
fun testWarning(@NonNull string: String) { }
49+
--------
50+
51+
52+
src/test/pkg/test.kt:11:Error: Do not use @Nullable in Kotlin; the
53+
nullability is determined by the Kotlin type String not ending with ?
54+
which declares it not nullable, contradicting the annotation
55+
[KotlinNullnessAnnotation]
56+
57+
fun testError(@Nullable string: String) { }
58+
---------
59+
60+
61+
src/test/pkg/test.kt:15:Error: Do not use @NonNull in Kotlin; the
62+
nullability is determined by the Kotlin type Number? ending with ? which
63+
declares it nullable, contradicting the annotation
64+
[KotlinNullnessAnnotation]
65+
66+
fun testError(@NonNull number: Number?) { }
67+
--------
68+
69+
70+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71+
72+
Here is the source file referenced above:
73+
74+
`src/test/pkg/test.kt`:
75+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~kotlin linenumbers
76+
package test.pkg
77+
import androidx.annotation.NonNull
78+
import androidx.annotation.Nullable
79+
80+
// Here we have an already non-null string annotated with @NonNull;
81+
// warn, since this is redundant
82+
fun testWarning(@NonNull string: String) { }
83+
84+
// Here we have a non-null string which has been annotated with @Nullable,
85+
// which is totally misleading; the annotation is wrong
86+
fun testError(@Nullable string: String) { }
87+
88+
// Here we have a nullable string which has been annotated with @NonNull,
89+
// which is totally misleading; the annotation is wrong.
90+
fun testError(@NonNull number: Number?) { }
91+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92+
93+
You can also visit the
94+
[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/KotlinNullnessAnnotationDetectorTest.kt)
95+
for the unit tests for this check to see additional scenarios.
96+
97+
(##) Suppressing
98+
99+
You can suppress false positives using one of the following mechanisms:
100+
101+
* Using a suppression annotation like this on the enclosing
102+
element:
103+
104+
```kt
105+
// Kotlin
106+
@Suppress("KotlinNullnessAnnotation")
107+
fun method() {
108+
problematicStatement()
109+
}
110+
```
111+
112+
or
113+
114+
```java
115+
// Java
116+
@SuppressWarnings("KotlinNullnessAnnotation")
117+
void method() {
118+
problematicStatement();
119+
}
120+
```
121+
122+
* Using a suppression comment like this on the line above:
123+
124+
```kt
125+
//noinspection KotlinNullnessAnnotation
126+
problematicStatement()
127+
```
128+
129+
* Using a special `lint.xml` file in the source tree which turns off
130+
the check in that folder and any sub folder. A simple file might look
131+
like this:
132+
```xml
133+
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
134+
&lt;lint&gt;
135+
&lt;issue id="KotlinNullnessAnnotation" severity="ignore" /&gt;
136+
&lt;/lint&gt;
137+
```
138+
Instead of `ignore` you can also change the severity here, for
139+
example from `error` to `warning`. You can find additional
140+
documentation on how to filter issues by path, regular expression and
141+
so on
142+
[here](https://googlesamples.github.io/android-custom-lint-rules/usage/lintxml.md.html).
143+
144+
* In Gradle projects, using the DSL syntax to configure lint. For
145+
example, you can use something like
146+
```gradle
147+
lintOptions {
148+
disable 'KotlinNullnessAnnotation'
149+
}
150+
```
151+
In Android projects this should be nested inside an `android { }`
152+
block.
153+
154+
* For manual invocations of `lint`, using the `--ignore` flag:
155+
```
156+
$ lint --ignore KotlinNullnessAnnotation ...`
157+
```
158+
159+
* Last, but not least, using baselines, as discussed
160+
[here](https://googlesamples.github.io/android-custom-lint-rules/usage/baselines.md.html).
161+
162+
<!-- 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/LaunchDuringComposition.md.html

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@
1818
: Jetpack Activity Compose
1919
Identifier
2020
: androidx.activity.compose
21+
Feedback
22+
: https://issuetracker.google.com/issues/new?component=612128
2123
Affects
2224
: Kotlin and Java files and test sources
2325
Editing
@@ -148,8 +150,8 @@
148150

149151
The above example was automatically extracted from the first unit test
150152
found for this lint check, `ActivityResultLaunchDetector.errors`.
151-
To report a problem with this extracted sample, contact
152-
Jetpack Activity Compose.
153+
To report a problem with this extracted sample, visit
154+
https://issuetracker.google.com/issues/new?component=612128.
153155

154156
(##) Suppressing
155157

‎docs/checks/NonResizeableActivity.md.html

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,9 @@
4747
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~text
4848
AndroidManifest.xml:5:Warning: Expecting
4949
android:resizeableActivity="true" for this activity so the user can take
50-
advantage of the multi-window environment on Chrome OS devices
51-
[NonResizeableActivity]
50+
advantage of the multi-window environment on all devices. NOTE:
51+
beginning with Android 12, all apps run in multi-window mode on large
52+
screen devices. [NonResizeableActivity]
5253

5354
&lt;activity android:name=".MainActivity" android:resizeableActivity="false"/&gt;
5455
----------------------------------

‎docs/checks/RemoveWorkManagerInitializer.md.html

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@
1717
Platform
1818
: Android
1919
Vendor
20-
: Android Open Source Project (androidx.work.lint.workmanager)
20+
: Android Open Source Project
2121
Identifier
22-
: androidx.work.lint.workmanager
22+
: androidx.work
2323
Feedback
24-
: https://issuetracker.google.com/issues/new?component=192731
24+
: https://issuetracker.google.com/issues/new?component=409906
2525
Affects
2626
: Kotlin and Java files and manifest files
2727
Editing
@@ -79,7 +79,7 @@
7979
The above example was automatically extracted from the first unit test
8080
found for this lint check, `RemoveWorkManagerInitializerDetector.failWhenManifestHasDefaultInitializer`.
8181
To report a problem with this extracted sample, visit
82-
https://issuetracker.google.com/issues/new?component=192731.
82+
https://issuetracker.google.com/issues/new?component=409906.
8383

8484
(##) Suppressing
8585

‎docs/checks/SpecifyForegroundServiceType.md.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@
1717
Platform
1818
: Android
1919
Vendor
20-
: Android Open Source Project (androidx.work.lint.workmanager)
20+
: Android Open Source Project
2121
Identifier
22-
: androidx.work.lint.workmanager
22+
: androidx.work
2323
Feedback
24-
: https://issuetracker.google.com/issues/new?component=192731
24+
: https://issuetracker.google.com/issues/new?component=409906
2525
Affects
2626
: Kotlin and Java files and manifest files
2727
Editing

0 commit comments

Comments
 (0)