-
Notifications
You must be signed in to change notification settings - Fork 174
/
Copy pathapi-guide.html
7065 lines (5387 loc) · 421 KB
/
api-guide.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html><head><meta charset="utf-8" lang="kotlin">
</head><body style="visibility: visible;" id="md"><meta charset="UTF-8"><meta http-equiv="content-type" content="text/html;charset=UTF-8"><meta name="viewport" content="width=600, initial-scale=1"><style>body{max-width:680px;margin:auto;padding:20px;text-align:justify;line-height:140%;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;font-smoothing:antialiased;color:#222;font-family:Palatino,Georgia,"Times New Roman",serif}</style><style>@media print{*{-webkit-print-color-adjust:exact;text-shadow:none !important}}body{counter-reset: h1 paragraph line item list-item}@page{margin:0;size:auto}#mdContextMenu{position:absolute;background:#383838;cursor:default;border:1px solid #999;color:#fff;padding:4px 0px;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen,Ubuntu,"Helvetica Neue",sans-serif;font-size:85%;font-weight:600;border-radius:4px;box-shadow:0px 3px 10px rgba(0,0,0,35%)}#mdContextMenu div{padding:0px 20px}#mdContextMenu div:hover{background:#1659d1}.md code,.md pre{font-family:Menlo,Consolas,monospace;font-size:85%;text-align:left;line-height:140%}.md .mediumToc code,.md longToc code,.md .shortToc code,.md h1 code,.md h2 code,.md h3 code,.md h4 code,.md h5 code,.md h6 code{font-size:unset}.md div.title{font-size:26px;font-weight:800;line-height:120%;text-align:center}.md div.afterTitles{height:10px}.md div.subtitle{text-align:center}.md iframe.textinsert, .md object.textinsert,.md iframe:not(.markdeep){display:block;margin-top:10px;margin-bottom:10px;width:100%;height:75vh;border:1px solid #000;border-radius:4px;background:#f5f5f4}.md .image{display:inline-block}.md img{max-width:100%;page-break-inside:avoid}.md li{text-align:left;text-indent:0}.md pre.listing {width:100%;tab-size:4;-moz-tab-size:4;-o-tab-size:4;counter-reset:line;overflow-x:auto;resize:horizontal}.md pre.listing .linenumbers span.line:before{width:30px;margin-left:-28px;font-size:80%;text-align:right;counter-increment:line;content:counter(line);display:inline-block;padding-right:13px;margin-right:8px;color:#ccc}.md div.tilde{margin:20px 0 -10px;text-align:center}.md .imagecaption,.md .tablecaption,.md .listingcaption{display:inline-block;margin:7px 5px 12px;text-align:justify;font-style:italic}.md img.pixel{image-rendering:-moz-crisp-edges;image-rendering:pixelated}.md blockquote.fancyquote{margin:25px 0 25px;text-align:left;line-height:160%}.md blockquote.fancyquote::before{content:"“";color:#DDD;font-family:Times New Roman;font-size:45px;line-height:0;margin-right:6px;vertical-align:-0.3em}.md span.fancyquote{font-size:118%;color:#777;font-style:italic}.md span.fancyquote::after{content:"”";font-style:normal;color:#DDD;font-family:Times New Roman;font-size:45px;line-height:0;margin-left:6px;vertical-align:-0.3em}.md blockquote.fancyquote .author{width:100%;margin-top:10px;display:inline-block;text-align:right}.md small{font-size:60%}.md big{font-size:150%}.md div.title,contents,.md .tocHeader,.md h1,.md h2,.md h3,.md h4,.md h5,.md h6,.md .shortTOC,.md .mediumTOC,.nonumberh1,.nonumberh2,.nonumberh3,.nonumberh4,.nonumberh5,.nonumberh6{font-family:Verdana,Helvetica,Arial,sans-serif;margin:13.4px 0 13.4px;padding:15px 0 3px;border-top:none;clear:both}.md .tocTop {display:none}.md h1,.md h2,.md h3,.md h4,.md h5,.md h6,.md .nonumberh1,.md .nonumberh2,.md .nonumberh3,.md .nonumberh4,.md .nonumberh5,.md .nonumberh6{page-break-after:avoid;break-after:avoid}.md svg.diagram{display:block;font-family:Menlo,Consolas,monospace;font-size:85%;text-align:center;stroke-linecap:round;stroke-width:2px;page-break-inside:avoid;stroke:#000;fill:#000}.md svg.diagram .opendot{fill:#fff}.md svg.diagram .shadeddot{fill:#CCC}.md svg.diagram .dotteddot{stroke:#000;stroke-dasharray:4;fill:none}.md svg.diagram text{stroke:none}@media print{@page{margin:1in 5mm;transform: scale(150%)}}@media print{.md .pagebreak{page-break-after:always;visibility:hidden}}.md a{font-family:Georgia,Palatino,'Times New Roman'}.md h1,.md .tocHeader,.md .nonumberh1{border-bottom:3px solid;font-size:20px;font-weight:bold;}.md h1,.md .nonumberh1{counter-reset:h2 h3 h4 h5 h6}.md h2,.md .nonumberh2{counter-reset:h3 h4 h5 h6;border-bottom:2px solid #999;color:#555;font-weight:bold;font-size:18px;}.md h3,.md h4,.md h5,.md h6,.md .nonumberh3,.md .nonumberh4,.md .nonumberh5,.md .nonumberh6{font-family:Verdana,Helvetica,Arial,sans-serif;color:#555;font-size:16px;}.md h3{counter-reset:h4 h5 h6}.md h4{counter-reset:h5 h6}.md h5{counter-reset:h6}.md div.table{margin:16px 0 16px 0}.md table{border-collapse:collapse;line-height:140%;page-break-inside:avoid}.md table.table{margin:auto}.md table.calendar{width:100%;margin:auto;font-size:11px;font-family:Verdana,Helvetica,Arial,sans-serif}.md table.calendar th{font-size:16px}.md .today{background:#ECF8FA}.md .calendar .parenthesized{color:#999;font-style:italic}.md table.table th{color:#FFF;background-color:#AAA;border:1px solid #888;padding:8px 15px 8px 15px}.md table.table td{padding:5px 15px 5px 15px;border:1px solid #888}.md table.table tr:nth-child(even){background:#EEE}.md pre.tilde{border-top: 1px solid #CCC;border-bottom: 1px solid #CCC;padding: 5px 0 5px 20px;margin:0 0 0 0;background:#FCFCFC;page-break-inside:avoid}.md a.target{width:0px;height:0px;visibility:hidden;font-size:0px;display:inline-block}.md a:link, .md a:visited{color:#38A;text-decoration:none}.md a:link:hover{text-decoration:underline}.md dt{font-weight:700}.md dl>dd{margin-top:-8px; margin-bottom:8px}.md dl>table{margin:35px 0 30px}.md code{page-break-inside:avoid;} @media print{.md .listing code{white-space:pre-wrap}}.md .endnote{font-size:13px;line-height:15px;padding-left:10px;text-indent:-10px}.md .bib{padding-left:80px;text-indent:-80px;text-align:left}.markdeepFooter{font-size:9px;text-align:right;padding-top:80px;color:#999}.md .mediumTOC{float:right;font-size:12px;line-height:15px;border-left:1px solid #CCC;padding-left:15px;margin:15px 0px 15px 25px}.md .mediumTOC .level1{font-weight:600}.md .longTOC .level1{font-weight:600;display:block;padding-top:12px;margin:0 0 -20px}.md .shortTOC{text-align:center;font-weight:bold;margin-top:15px;font-size:14px}.md .admonition{position:relative;margin:1em 0;padding:.4rem 1rem;border-radius:.2rem;border-left:2.5rem solid rgba(68,138,255,.4);background-color:rgba(68,138,255,.15);}.md .admonition-title{font-weight:bold;border-bottom:solid 1px rgba(68,138,255,.4);padding-bottom:4px;margin-bottom:4px;margin-left: -1rem;padding-left:1rem;margin-right:-1rem;border-color:rgba(68,138,255,.4)}.md .admonition.tip{border-left:2.5rem solid rgba(50,255,90,.4);background-color:rgba(50,255,90,.15)}.md .admonition.tip::before{content:"\24d8";font-weight:bold;font-size:150%;position:relative;top:3px;color:rgba(26,128,46,.8);left:-2.95rem;display:block;width:0;height:0}.md .admonition.tip>.admonition-title{border-color:rgba(50,255,90,.4)}.md .admonition.warn,.md .admonition.warning{border-left:2.5rem solid rgba(255,145,0,.4);background-color:rgba(255,145,0,.15)}.md .admonition.warn::before,.md .admonition.warning::before{content:"\26A0";font-weight:bold;font-size:150%;position:relative;top:2px;color:rgba(128,73,0,.8);left:-2.95rem;display:block;width:0;height:0}.md .admonition.warn>.admonition-title,.md .admonition.warning>.admonition-title{border-color:rgba(255,145,0,.4)}.md .admonition.error{border-left: 2.5rem solid rgba(255,23,68,.4);background-color:rgba(255,23,68,.15)}.md .admonition.error>.admonition-title{border-color:rgba(255,23,68,.4)}.md .admonition.error::before{content: "\2612";font-family:"Arial";font-size:200%;position:relative;color:rgba(128,12,34,.8);top:-2px;left:-3rem;display:block;width:0;height:0}.md .admonition p:last-child{margin-bottom:0}.md li.checked,.md li.unchecked{list-style:none;overflow:visible;text-indent:-1.2em}.md li.checked:before,.md li.unchecked:before{content:"\2611";display:block;float:left;width:1em;font-size:120%}.md li.unchecked:before{content:"\2610"}</style><style>.md h1::before {
content:counter(h1) " ";
counter-increment: h1;margin-right:10px}
.md h2::before {
content:counter(h1) "."counter(h2) " ";
counter-increment: h2;margin-right:10px}
.md h3::before {
content:counter(h1) "."counter(h2) "."counter(h3) " ";
counter-increment: h3;margin-right:10px}
.md h4::before {
content:counter(h1) "."counter(h2) "."counter(h3) "."counter(h4) " ";
counter-increment: h4;margin-right:10px}
.md h5::before {
content:counter(h1) "."counter(h2) "."counter(h3) "."counter(h4) "."counter(h5) " ";
counter-increment: h5;margin-right:10px}
.md h6::before {
content:counter(h1) "."counter(h2) "."counter(h3) "."counter(h4) "."counter(h5) "."counter(h6) " ";
counter-increment: h6;margin-right:10px}
</style><style>.hljs{display:block;overflow-x:auto;padding:0.5em;background:#fff;color:#000;-webkit-text-size-adjust:none}.hljs-comment{color:#006a00}.hljs-keyword{color:#02E}.hljs-literal,.nginx .hljs-title{color:#aa0d91}.method,.hljs-list .hljs-title,.hljs-tag .hljs-title,.setting .hljs-value,.hljs-winutils,.tex .hljs-command,.http .hljs-title,.hljs-request,.hljs-status,.hljs-name{color:#008}.hljs-envvar,.tex .hljs-special{color:#660}.hljs-string{color:#c41a16}.hljs-tag .hljs-value,.hljs-cdata,.hljs-filter .hljs-argument,.hljs-attr_selector,.apache .hljs-cbracket,.hljs-date,.hljs-regexp{color:#080}.hljs-sub .hljs-identifier,.hljs-pi,.hljs-tag,.hljs-tag .hljs-keyword,.hljs-decorator,.ini .hljs-title,.hljs-shebang,.hljs-prompt,.hljs-hexcolor,.hljs-rule .hljs-value,.hljs-symbol,.hljs-symbol .hljs-string,.hljs-number,.css .hljs-function,.hljs-function .hljs-title,.coffeescript .hljs-attribute{color:#A0C}.hljs-function .hljs-title{font-weight:bold;color:#000}.hljs-class .hljs-title,.smalltalk .hljs-class,.hljs-type,.hljs-typename,.hljs-tag .hljs-attribute,.hljs-doctype,.hljs-class .hljs-id,.hljs-built_in,.setting,.hljs-params,.clojure .hljs-attribute{color:#5c2699}.hljs-variable{color:#3f6e74}.css .hljs-tag,.hljs-rule .hljs-property,.hljs-pseudo,.hljs-subst{color:#000}.css .hljs-class,.css .hljs-id{color:#9b703f}.hljs-value .hljs-important{color:#ff7700;font-weight:bold}.hljs-rule .hljs-keyword{color:#c5af75}.hljs-annotation,.apache .hljs-sqbracket,.nginx .hljs-built_in{color:#9b859d}.hljs-preprocessor,.hljs-preprocessor *,.hljs-pragma{color:#643820}.tex .hljs-formula{background-color:#eee;font-style:italic}.diff .hljs-header,.hljs-chunk{color:#808080;font-weight:bold}.diff .hljs-change{background-color:#bccff9}.hljs-addition{background-color:#baeeba}.hljs-deletion{background-color:#ffc8bd}.hljs-comment .hljs-doctag{font-weight:bold}.method .hljs-id{color:#000}</style><style>div.title { padding-top: 40px; } div.afterTitles { height: 15px; }</style><meta charset="utf-8" lang="kotlin">
<script type="text/x-mathjax-config">MathJax.Hub.Config({ TeX: { equationNumbers: {autoNumber: "AMS"} } });</script><span style="display:none">$$\newcommand{\n}{\hat{n}}\newcommand{\thetai}{\theta_\mathrm{i}}\newcommand{\thetao}{\theta_\mathrm{o}}\newcommand{\d}[1]{\mathrm{d}#1}\newcommand{\w}{\hat{\omega}}\newcommand{\wi}{\w_\mathrm{i}}\newcommand{\wo}{\w_\mathrm{o}}\newcommand{\wh}{\w_\mathrm{h}}\newcommand{\Li}{L_\mathrm{i}}\newcommand{\Lo}{L_\mathrm{o}}\newcommand{\Le}{L_\mathrm{e}}\newcommand{\Lr}{L_\mathrm{r}}\newcommand{\Lt}{L_\mathrm{t}}\newcommand{\O}{\mathrm{O}}\newcommand{\degrees}{{^{\large\circ}}}\newcommand{\T}{\mathsf{T}}\newcommand{\mathset}[1]{\mathbb{#1}}\newcommand{\Real}{\mathset{R}}\newcommand{\Integer}{\mathset{Z}}\newcommand{\Boolean}{\mathset{B}}\newcommand{\Complex}{\mathset{C}}\newcommand{\un}[1]{\,\mathrm{#1}}$$
</span>
<span class="md"><p><title>Android Lint API Guide</title></p><div class="title"> Android Lint API Guide </div>
<div class="afterTitles"></div>
<p></p><p>
This chapter inlines all the API documentation into a single
long book, suitable for printing or reading on a tablet.
</p>
<div class="longTOC"><div class="tocHeader">Contents</div><p><a href="#" class="tocTop">(Top)</a><br>
<a href="#terminology" class="level1"><span class="tocNumber">1 </span>Terminology</a><br>
<a href="#writingalintcheck:basics" class="level1"><span class="tocNumber">2 </span>Writing a Lint Check: Basics</a><br>
<a href="#writingalintcheck:basics/preliminaries" class="level2"><span class="tocNumber">2.1 </span>Preliminaries</a><br>
<a href="#writingalintcheck:basics/preliminaries/%E2%80%9Clint?%E2%80%9D" class="level3"><span class="tocNumber">2.1.1 </span>“Lint?”</a><br>
<a href="#writingalintcheck:basics/preliminaries/apistability" class="level3"><span class="tocNumber">2.1.2 </span>API Stability</a><br>
<a href="#writingalintcheck:basics/preliminaries/kotlin" class="level3"><span class="tocNumber">2.1.3 </span>Kotlin</a><br>
<a href="#writingalintcheck:basics/concepts" class="level2"><span class="tocNumber">2.2 </span>Concepts</a><br>
<a href="#writingalintcheck:basics/clientapiversusdetectorapi" class="level2"><span class="tocNumber">2.3 </span>Client API versus Detector API</a><br>
<a href="#writingalintcheck:basics/creatinganissue" class="level2"><span class="tocNumber">2.4 </span>Creating an Issue</a><br>
<a href="#writingalintcheck:basics/textformat" class="level2"><span class="tocNumber">2.5 </span>TextFormat</a><br>
<a href="#writingalintcheck:basics/issueimplementation" class="level2"><span class="tocNumber">2.6 </span>Issue Implementation</a><br>
<a href="#writingalintcheck:basics/scopes" class="level2"><span class="tocNumber">2.7 </span>Scopes</a><br>
<a href="#writingalintcheck:basics/registeringtheissue" class="level2"><span class="tocNumber">2.8 </span>Registering the Issue</a><br>
<a href="#writingalintcheck:basics/implementingadetector:scanners" class="level2"><span class="tocNumber">2.9 </span>Implementing a Detector: Scanners</a><br>
<a href="#writingalintcheck:basics/detectorlifecycle" class="level2"><span class="tocNumber">2.10 </span>Detector Lifecycle</a><br>
<a href="#writingalintcheck:basics/scannerorder" class="level2"><span class="tocNumber">2.11 </span>Scanner Order</a><br>
<a href="#writingalintcheck:basics/implementingadetector:services" class="level2"><span class="tocNumber">2.12 </span>Implementing a Detector: Services</a><br>
<a href="#writingalintcheck:basics/scannerexample" class="level2"><span class="tocNumber">2.13 </span>Scanner Example</a><br>
<a href="#writingalintcheck:basics/analyzingkotlinandjavacode" class="level2"><span class="tocNumber">2.14 </span>Analyzing Kotlin and Java Code</a><br>
<a href="#writingalintcheck:basics/analyzingkotlinandjavacode/uast" class="level3"><span class="tocNumber">2.14.1 </span>UAST</a><br>
<a href="#writingalintcheck:basics/analyzingkotlinandjavacode/uastexample" class="level3"><span class="tocNumber">2.14.2 </span>UAST Example</a><br>
<a href="#writingalintcheck:basics/analyzingkotlinandjavacode/lookingupuast" class="level3"><span class="tocNumber">2.14.3 </span>Looking up UAST</a><br>
<a href="#writingalintcheck:basics/analyzingkotlinandjavacode/resolving" class="level3"><span class="tocNumber">2.14.4 </span>Resolving</a><br>
<a href="#writingalintcheck:basics/analyzingkotlinandjavacode/implicitcalls" class="level3"><span class="tocNumber">2.14.5 </span>Implicit Calls</a><br>
<a href="#writingalintcheck:basics/analyzingkotlinandjavacode/psi" class="level3"><span class="tocNumber">2.14.6 </span>PSI</a><br>
<a href="#writingalintcheck:basics/testing" class="level2"><span class="tocNumber">2.15 </span>Testing</a><br>
<a href="#example:samplelintcheckgithubproject" class="level1"><span class="tocNumber">3 </span>Example: Sample Lint Check GitHub Project</a><br>
<a href="#example:samplelintcheckgithubproject/projectlayout" class="level2"><span class="tocNumber">3.1 </span>Project Layout</a><br>
<a href="#example:samplelintcheckgithubproject/:checks" class="level2"><span class="tocNumber">3.2 </span>:checks</a><br>
<a href="#example:samplelintcheckgithubproject/lintversion?" class="level2"><span class="tocNumber">3.3 </span>lintVersion?</a><br>
<a href="#example:samplelintcheckgithubproject/:libraryand:app" class="level2"><span class="tocNumber">3.4 </span>:library and :app</a><br>
<a href="#example:samplelintcheckgithubproject/lintcheckprojectlayout" class="level2"><span class="tocNumber">3.5 </span>Lint Check Project Layout</a><br>
<a href="#example:samplelintcheckgithubproject/serviceregistration" class="level2"><span class="tocNumber">3.6 </span>Service Registration</a><br>
<a href="#example:samplelintcheckgithubproject/issueregistry" class="level2"><span class="tocNumber">3.7 </span>IssueRegistry</a><br>
<a href="#example:samplelintcheckgithubproject/detector" class="level2"><span class="tocNumber">3.8 </span>Detector</a><br>
<a href="#example:samplelintcheckgithubproject/detectortest" class="level2"><span class="tocNumber">3.9 </span>Detector Test</a><br>
<a href="#publishingalintcheck" class="level1"><span class="tocNumber">4 </span>Publishing a Lint Check</a><br>
<a href="#publishingalintcheck/android" class="level2"><span class="tocNumber">4.1 </span>Android</a><br>
<a href="#publishingalintcheck/android/aarsupport" class="level3"><span class="tocNumber">4.1.1 </span>AAR Support</a><br>
<a href="#publishingalintcheck/android/lintpublishconfiguration" class="level3"><span class="tocNumber">4.1.2 </span>lintPublish Configuration</a><br>
<a href="#publishingalintcheck/android/localchecks" class="level3"><span class="tocNumber">4.1.3 </span>Local Checks</a><br>
<a href="#publishingalintcheck/android/unpublishing" class="level3"><span class="tocNumber">4.1.4 </span>Unpublishing</a><br>
<a href="#lintcheckunittesting" class="level1"><span class="tocNumber">5 </span>Lint Check Unit Testing</a><br>
<a href="#lintcheckunittesting/creatingaunittest" class="level2"><span class="tocNumber">5.1 </span>Creating a Unit Test</a><br>
<a href="#lintcheckunittesting/computingtheexpectedoutput" class="level2"><span class="tocNumber">5.2 </span>Computing the Expected Output</a><br>
<a href="#lintcheckunittesting/testfiles" class="level2"><span class="tocNumber">5.3 </span>Test Files</a><br>
<a href="#lintcheckunittesting/trimmingindents?" class="level2"><span class="tocNumber">5.4 </span>Trimming indents?</a><br>
<a href="#lintcheckunittesting/dollarsinrawstrings" class="level2"><span class="tocNumber">5.5 </span>Dollars in Raw Strings</a><br>
<a href="#lintcheckunittesting/quickfixes" class="level2"><span class="tocNumber">5.6 </span>Quickfixes</a><br>
<a href="#lintcheckunittesting/librarydependenciesandstubs" class="level2"><span class="tocNumber">5.7 </span>Library Dependencies and Stubs</a><br>
<a href="#lintcheckunittesting/binaryandcompiledsourcefiles" class="level2"><span class="tocNumber">5.8 </span>Binary and Compiled Source Files</a><br>
<a href="#lintcheckunittesting/mydetectorisn'tinvokedfromatest!" class="level2"><span class="tocNumber">5.9 </span>My Detector Isn't Invoked From a Test!</a><br>
<a href="#testmodes" class="level1"><span class="tocNumber">6 </span>Test Modes</a><br>
<a href="#testmodes/howtodebug" class="level2"><span class="tocNumber">6.1 </span>How to debug</a><br>
<a href="#testmodes/handlingintentionalfailures" class="level2"><span class="tocNumber">6.2 </span>Handling Intentional Failures</a><br>
<a href="#testmodes/source-modifyingtestmodes" class="level2"><span class="tocNumber">6.3 </span>Source-Modifying Test Modes</a><br>
<a href="#testmodes/source-modifyingtestmodes/fullyqualifiednames" class="level3"><span class="tocNumber">6.3.1 </span>Fully Qualified Names</a><br>
<a href="#testmodes/source-modifyingtestmodes/importaliasing" class="level3"><span class="tocNumber">6.3.2 </span>Import Aliasing</a><br>
<a href="#testmodes/source-modifyingtestmodes/typealiasing" class="level3"><span class="tocNumber">6.3.3 </span>Type Aliasing</a><br>
<a href="#testmodes/source-modifyingtestmodes/parenthesismode" class="level3"><span class="tocNumber">6.3.4 </span>Parenthesis Mode</a><br>
<a href="#testmodes/source-modifyingtestmodes/argumentreordering" class="level3"><span class="tocNumber">6.3.5 </span>Argument Reordering</a><br>
<a href="#testmodes/source-modifyingtestmodes/bodyremoval" class="level3"><span class="tocNumber">6.3.6 </span>Body Removal</a><br>
<a href="#testmodes/source-modifyingtestmodes/iftowhenreplacement" class="level3"><span class="tocNumber">6.3.7 </span>If to When Replacement</a><br>
<a href="#testmodes/source-modifyingtestmodes/whitespacemode" class="level3"><span class="tocNumber">6.3.8 </span>Whitespace Mode</a><br>
<a href="#testmodes/source-modifyingtestmodes/cdatamode" class="level3"><span class="tocNumber">6.3.9 </span>CDATA Mode</a><br>
<a href="#addingquickfixes" class="level1"><span class="tocNumber">7 </span>Adding Quick Fixes</a><br>
<a href="#addingquickfixes/introduction" class="level2"><span class="tocNumber">7.1 </span>Introduction</a><br>
<a href="#addingquickfixes/thelintfixbuilderclass" class="level2"><span class="tocNumber">7.2 </span>The LintFix builder class</a><br>
<a href="#addingquickfixes/creatingalintfix" class="level2"><span class="tocNumber">7.3 </span>Creating a LintFix</a><br>
<a href="#addingquickfixes/availablefixes" class="level2"><span class="tocNumber">7.4 </span>Available Fixes</a><br>
<a href="#addingquickfixes/combiningfixes" class="level2"><span class="tocNumber">7.5 </span>Combining Fixes</a><br>
<a href="#addingquickfixes/refactoringjavaandkotlincode" class="level2"><span class="tocNumber">7.6 </span>Refactoring Java and Kotlin code</a><br>
<a href="#addingquickfixes/regularexpressionsandbackreferences" class="level2"><span class="tocNumber">7.7 </span>Regular Expressions and Back References</a><br>
<a href="#addingquickfixes/emittingquickfixxmltoapplyonci" class="level2"><span class="tocNumber">7.8 </span>Emitting quick fix XML to apply on CI</a><br>
<a href="#partialanalysis" class="level1"><span class="tocNumber">8 </span>Partial Analysis</a><br>
<a href="#partialanalysis/about" class="level2"><span class="tocNumber">8.1 </span>About</a><br>
<a href="#partialanalysis/theproblem" class="level2"><span class="tocNumber">8.2 </span>The Problem</a><br>
<a href="#partialanalysis/overview" class="level2"><span class="tocNumber">8.3 </span>Overview</a><br>
<a href="#partialanalysis/doesmydetectorneedwork?" class="level2"><span class="tocNumber">8.4 </span>Does My Detector Need Work?</a><br>
<a href="#partialanalysis/doesmydetectorneedwork?/catchingmistakes:blockingaccesstomainproject" class="level3"><span class="tocNumber">8.4.1 </span>Catching Mistakes: Blocking Access to Main Project</a><br>
<a href="#partialanalysis/doesmydetectorneedwork?/catchingmistakes:simulatedappmodule" class="level3"><span class="tocNumber">8.4.2 </span>Catching Mistakes: Simulated App Module</a><br>
<a href="#partialanalysis/doesmydetectorneedwork?/catchingmistakes:diffingresults" class="level3"><span class="tocNumber">8.4.3 </span>Catching Mistakes: Diffing Results</a><br>
<a href="#partialanalysis/doesmydetectorneedwork?/catchingmistakes:remainingissues" class="level3"><span class="tocNumber">8.4.4 </span>Catching Mistakes: Remaining Issues</a><br>
<a href="#partialanalysis/incidents" class="level2"><span class="tocNumber">8.5 </span>Incidents</a><br>
<a href="#partialanalysis/constraints" class="level2"><span class="tocNumber">8.6 </span>Constraints</a><br>
<a href="#partialanalysis/incidentlintmaps" class="level2"><span class="tocNumber">8.7 </span>Incident LintMaps</a><br>
<a href="#partialanalysis/modulelintmaps" class="level2"><span class="tocNumber">8.8 </span>Module LintMaps</a><br>
<a href="#partialanalysis/optimizations" class="level2"><span class="tocNumber">8.9 </span>Optimizations</a><br>
<a href="#dataflowanalyzer" class="level1"><span class="tocNumber">9 </span>Data Flow Analyzer</a><br>
<a href="#dataflowanalyzer/usage" class="level2"><span class="tocNumber">9.1 </span>Usage</a><br>
<a href="#dataflowanalyzer/self-referencingcalls" class="level2"><span class="tocNumber">9.2 </span>Self-referencing Calls</a><br>
<a href="#dataflowanalyzer/kotlinscopingfunctions" class="level2"><span class="tocNumber">9.3 </span>Kotlin Scoping Functions</a><br>
<a href="#dataflowanalyzer/limitations" class="level2"><span class="tocNumber">9.4 </span>Limitations</a><br>
<a href="#dataflowanalyzer/escapingvalues" class="level2"><span class="tocNumber">9.5 </span>Escaping Values</a><br>
<a href="#dataflowanalyzer/escapingvalues/returns" class="level3"><span class="tocNumber">9.5.1 </span>Returns</a><br>
<a href="#dataflowanalyzer/escapingvalues/parameters" class="level3"><span class="tocNumber">9.5.2 </span>Parameters</a><br>
<a href="#dataflowanalyzer/escapingvalues/fields" class="level3"><span class="tocNumber">9.5.3 </span>Fields</a><br>
<a href="#dataflowanalyzer/nonlocalanalysis" class="level2"><span class="tocNumber">9.6 </span>Non Local Analysis</a><br>
<a href="#dataflowanalyzer/examples" class="level2"><span class="tocNumber">9.7 </span>Examples</a><br>
<a href="#dataflowanalyzer/examples/simpleexample" class="level3"><span class="tocNumber">9.7.1 </span>Simple Example</a><br>
<a href="#dataflowanalyzer/examples/complexexample" class="level3"><span class="tocNumber">9.7.2 </span>Complex Example</a><br>
<a href="#annotations" class="level1"><span class="tocNumber">10 </span>Annotations</a><br>
<a href="#annotations/basics" class="level2"><span class="tocNumber">10.1 </span>Basics</a><br>
<a href="#annotations/annotationusagetypesandisapplicableannotationusage" class="level2"><span class="tocNumber">10.2 </span>Annotation Usage Types and isApplicableAnnotationUsage</a><br>
<a href="#annotations/annotationusagetypesandisapplicableannotationusage/methodoverride" class="level3"><span class="tocNumber">10.2.1 </span>Method Override</a><br>
<a href="#annotations/annotationusagetypesandisapplicableannotationusage/methodreturn" class="level3"><span class="tocNumber">10.2.2 </span>Method Return</a><br>
<a href="#annotations/annotationusagetypesandisapplicableannotationusage/handlingusagetypes" class="level3"><span class="tocNumber">10.2.3 </span>Handling Usage Types</a><br>
<a href="#annotations/annotationusagetypesandisapplicableannotationusage/usagetypesfilteredbydefault" class="level3"><span class="tocNumber">10.2.4 </span>Usage Types Filtered By Default</a><br>
<a href="#annotations/annotationusagetypesandisapplicableannotationusage/scopes" class="level3"><span class="tocNumber">10.2.5 </span>Scopes</a><br>
<a href="#annotations/annotationusagetypesandisapplicableannotationusage/inheritedannotations" class="level3"><span class="tocNumber">10.2.6 </span>Inherited Annotations</a><br>
<a href="#options" class="level1"><span class="tocNumber">11 </span>Options</a><br>
<a href="#options/usage" class="level2"><span class="tocNumber">11.1 </span>Usage</a><br>
<a href="#options/creatingoptions" class="level2"><span class="tocNumber">11.2 </span>Creating Options</a><br>
<a href="#options/readingoptions" class="level2"><span class="tocNumber">11.3 </span>Reading Options</a><br>
<a href="#options/specificconfigurations" class="level2"><span class="tocNumber">11.4 </span>Specific Configurations</a><br>
<a href="#options/files" class="level2"><span class="tocNumber">11.5 </span>Files</a><br>
<a href="#options/constraints" class="level2"><span class="tocNumber">11.6 </span>Constraints</a><br>
<a href="#options/testingoptions" class="level2"><span class="tocNumber">11.7 </span>Testing Options</a><br>
<a href="#options/supportinglint4.2,7.0and7.1" class="level2"><span class="tocNumber">11.8 </span>Supporting Lint 4.2, 7.0 and 7.1</a><br>
<a href="#errormessageconventions" class="level1"><span class="tocNumber">12 </span>Error Message Conventions</a><br>
<a href="#errormessageconventions/length" class="level2"><span class="tocNumber">12.1 </span>Length</a><br>
<a href="#errormessageconventions/formatting" class="level2"><span class="tocNumber">12.2 </span>Formatting</a><br>
<a href="#errormessageconventions/punctuation" class="level2"><span class="tocNumber">12.3 </span>Punctuation</a><br>
<a href="#errormessageconventions/includedetails" class="level2"><span class="tocNumber">12.4 </span>Include Details</a><br>
<a href="#errormessageconventions/referenceandroidbynumber" class="level2"><span class="tocNumber">12.5 </span>Reference Android By Number</a><br>
<a href="#errormessageconventions/keepmessagesstable" class="level2"><span class="tocNumber">12.6 </span>Keep Messages Stable</a><br>
<a href="#errormessageconventions/examples" class="level2"><span class="tocNumber">12.7 </span>Examples</a><br>
<a href="#frequentlyaskedquestions" class="level1"><span class="tocNumber">13 </span>Frequently Asked Questions</a><br>
<a href="#frequentlyaskedquestions//mydetectorcallbacksaren'tinvoked" class="level3"><span class="tocNumber">13.0.1 </span>My detector callbacks aren't invoked</a><br>
<a href="#frequentlyaskedquestions//mylintcheckworksfromtheunittestbutnotintheide" class="level3"><span class="tocNumber">13.0.2 </span>My lint check works from the unit test but not in the IDE</a><br>
<a href="#frequentlyaskedquestions//visitannotationusageisn'tcalledforannotations" class="level3"><span class="tocNumber">13.0.3 </span><code>visitAnnotationUsage</code> isn't called for annotations</a><br>
<a href="#frequentlyaskedquestions//howdoicheckifauastorpsielementisforjavaorkotlin?" class="level3"><span class="tocNumber">13.0.4 </span>How do I check if a UAST or PSI element is for Java or Kotlin?</a><br>
<a href="#frequentlyaskedquestions//whatifineedapsielementandihaveauelement?" class="level3"><span class="tocNumber">13.0.5 </span>What if I need a <code>PsiElement</code> and I have a <code>UElement</code> ?</a><br>
<a href="#frequentlyaskedquestions//howdoigettheumethodforapsimethod?" class="level3"><span class="tocNumber">13.0.6 </span>How do I get the <code>UMethod</code> for a <code>PsiMethod</code> ?</a><br>
<a href="#frequentlyaskedquestions//howdogetajavaevaluator?" class="level3"><span class="tocNumber">13.0.7 </span>How do get a <code>JavaEvaluator</code> ?</a><br>
<a href="#frequentlyaskedquestions//howdoicheckwhetheranelementisinternal?" class="level3"><span class="tocNumber">13.0.8 </span>How do I check whether an element is internal?</a><br>
<a href="#frequentlyaskedquestions//iselementinline,sealed,operator,infix,suspend,data?" class="level3"><span class="tocNumber">13.0.9 </span>Is element inline, sealed, operator, infix, suspend, data?</a><br>
<a href="#frequentlyaskedquestions//howdoilookupaclassifihaveitsfullyqualifiedname?" class="level3"><span class="tocNumber">13.0.10 </span>How do I look up a class if I have its fully qualified name?</a><br>
<a href="#frequentlyaskedquestions//howdoilookupaclassifihaveapsitype?" class="level3"><span class="tocNumber">13.0.11 </span>How do I look up a class if I have a PsiType?</a><br>
<a href="#frequentlyaskedquestions//howdoilookuphierarhcyannotationsforanelement?" class="level3"><span class="tocNumber">13.0.12 </span>How do I look up hierarhcy annotations for an element?</a><br>
<a href="#frequentlyaskedquestions//howdoilookupifaclassisasubclassofanother?" class="level3"><span class="tocNumber">13.0.13 </span>How do I look up if a class is a subclass of another?</a><br>
<a href="#frequentlyaskedquestions//howdoiknowwhichparameteracallargumentcorrespondsto?" class="level3"><span class="tocNumber">13.0.14 </span>How do I know which parameter a call argument corresponds to?</a><br>
<a href="#frequentlyaskedquestions//howcanmylintcheckstargettwodifferentversionsoflint?" class="level3"><span class="tocNumber">13.0.15 </span>How can my lint checks target two different versions of lint?</a><br>
<a href="#frequentlyaskedquestions//canimakemylintcheck%E2%80%9Cnotsuppressible?%E2%80%9D" class="level3"><span class="tocNumber">13.0.16 </span>Can I make my lint check “not suppressible?”</a><br>
<a href="#frequentlyaskedquestions//whyareoverloadedoperatorsnothandled?" class="level3"><span class="tocNumber">13.0.17 </span>Why are overloaded operators not handled?</a><br>
<a href="#frequentlyaskedquestions//howdoicheckoutthecurrentlintsourcecode?" class="level3"><span class="tocNumber">13.0.18 </span>How do I check out the current lint source code?</a><br>
<a href="#frequentlyaskedquestions//wheredoifindexamplesoflintchecks?" class="level3"><span class="tocNumber">13.0.19 </span>Where do I find examples of lint checks?</a><br>
<a href="#appendix:recentchanges" class="level1"><span class="tocNumber">14 </span>Appendix: Recent Changes</a><br>
<a href="#appendix:environmentvariablesandsystemproperties" class="level1"><span class="tocNumber">15 </span>Appendix: Environment Variables and System Properties</a><br>
<a href="#appendix:environmentvariablesandsystemproperties/environmentvariables" class="level2"><span class="tocNumber">15.1 </span>Environment Variables</a><br>
<a href="#appendix:environmentvariablesandsystemproperties/environmentvariables/detectorconfigurationvariables" class="level3"><span class="tocNumber">15.1.1 </span>Detector Configuration Variables</a><br>
<a href="#appendix:environmentvariablesandsystemproperties/environmentvariables/lintconfigurationvariables" class="level3"><span class="tocNumber">15.1.2 </span>Lint Configuration Variables</a><br>
<a href="#appendix:environmentvariablesandsystemproperties/environmentvariables/lintdevelopmentvariables" class="level3"><span class="tocNumber">15.1.3 </span>Lint Development Variables</a><br>
<a href="#appendix:environmentvariablesandsystemproperties/systemproperties" class="level2"><span class="tocNumber">15.2 </span>System Properties</a><br>
</p></div><a class="target" name="terminology"> </a><a class="target" name="terminology"> </a><a class="target" name="toc1"> </a><h1>Terminology</h1>
<p>
You don't need to read this up front and understand everything, but
this is hopefully a handy reference to return to.
</p><p>
In alphabetical order:
</p><p>
</p><dl><dt>Configuration</dt><dd><p> A configuration provides extra information or parameters to lint on a
per project, or even per directory basis. For example, the <code>lint.xml</code>
files can change the severity for issues, or list incidents to ignore
(matched for example by a regular expression), or even provide values
for options read by a specific detector.
</p></dd><dt>Context</dt><dd><p> An object passed into detectors in many APIs, providing data about
(for example) which file is being analyzed (and in which project),
and for specific types of analysis additional information; for
example, an XmlContext points to the DOM document, a JavaContext
includes the AST, and so on.
</p></dd><dt>Detector</dt><dd><p> The implementation of the lint check which registers Issues, analyzes
the code, and reports Incidents.
</p></dd><dt>Implementation</dt><dd><p> An <code>Implementation</code> tells lint how a given issue is actually
analyzed, such as which detector class to instantiate, as well as
which scopes the detector applies to.
</p></dd><dt>Incident</dt><dd><p> A specific occurrence of the issue at a specific location.
An example of an incident is:
</p><pre class="listing backtick"><code><span class="line"></span> Warning: In file IoUtils.kt, line 140, the field download folder
<span class="line"></span> is "/sdcard/downloads"; do not hardcode the path to `/sdcard`.</code></pre></dd><dt>Issue</dt><dd><p> A type or class of problem that your lint check identifies. An issue
has an associated severity (error, warning or info), a priority, a
category, an explanation, and so on.
</p><p>
An example of an issue is “Don't hardcode paths to /sdcard”.
</p></dd><dt>IssueRegistry</dt><dd><p> An <code>IssueRegistry</code> provides a list of issues to lint. When you write
one or more lint checks, you'll register these in an <code>IssueRegistry</code>
and point to it using the <code>META-INF</code> service loader mechanism.
</p></dd><dt>LintClient</dt><dd><p> The <code>LintClient</code> represents the specific tool the detector is running
in. For example, when running in the IDE there is a LintClient which
(when incidents are reported) will show highlights in the editor,
whereas when lint is running as part of the Gradle plugin, incidents
are instead accumulated into HTML (and XML and text) reports, and
the build interrupted on error.
</p></dd><dt>Location</dt><dd><p> A “location” refers to a place where an incident is reported.
Typically this refers to a text range within a source file, but a
location can also point to a binary file such as a <code>png</code> file.
Locations can also be linked together, along with descriptions.
Therefore, if you for example are reporting a duplicate declaration,
you can include <strong class="asterisk">both</strong> Locations, and in the IDE, both locations
(if they're in the same file) will be highlighted. A location linked
from another is called a “secondary” location, but the chaining can
be as long as you want (and lint's unit testing infrastructure will
make sure there are no cycles.)
</p></dd><dt>Partial Analysis</dt><dd><p> A “map reduce” architecture in lint which makes it possible to
analyze individual modules in isolation and then later filter and
customize the partial results based on conditions outside of these
modules. This is explained in greater detail in the
<a href="#partialanalysis">partial analysis</a> chapter.
</p></dd><dt>Platform</dt><dd><p> The <code>Platform</code> abstraction allows lint issues to indicate where they
apply (such as “Android”, or “Server”, and so on). This means that an
Android-specific check won't trigger warnings on non-Android code.
</p></dd><dt>Scanner</dt><dd><p> A <code>Scanner</code> is a particular interface a detector can implement to
indicate that it supports a specific set of callbacks. For example,
the <code>XmlScanner</code> interface is where the methods for visiting XML
elements and attributes are defined, and the <code>ClassScanner</code> is where
the ASM bytecode handling methods are defined, and so on.
</p></dd><dt>Scope</dt><dd><p> <code>Scope</code> is an enum which lists various types of files that a detector
may want to analyze.
</p><p>
For example, there is a scope for XML files, there is a scope for
Java and Kotlin files, there is a scope for .class files, and so on.
</p><p>
Typically lint cares about which <strong class="asterisk">set</strong> of scopes apply,
so most of the APIs take an <code>EnumSet< Scope></code>, but we'll often
refer to this as just “the scope” instead of the “scope set”.
</p></dd><dt>Severity</dt><dd><p> For an issue, whether the incident should be an error, or just a
warning, or neither (just an FYI highlight). There is also a special
type of error severity, “fatal”, discussed later.
</p></dd><dt>TextFormat</dt><dd><p> An enum describing various text formats lint understands. Lint checks
will typically only operate with the “raw” format, which is
markdown-like (e.g. you can surround words with an asterisk to make
it italics or two to make it bold, and so on).
</p></dd><dt>Vendor</dt><dd><p> A <code>Vendor</code> is a simple data class which provides information about
the provenance of a lint check: who wrote it, where to file issues,
and so on.
</p></dd></dl><p></p>
<a class="target" name="writingalintcheck:basics"> </a><a class="target" name="writingalintcheck:basics"> </a><a class="target" name="toc2"> </a><h1>Writing a Lint Check: Basics</h1>
<a class="target" name="preliminaries"> </a><a class="target" name="writingalintcheck:basics/preliminaries"> </a><a class="target" name="toc2.1"> </a><h2>Preliminaries</h2>
<p>
(If you already know a lot of the basics but you're here because you've
run into a problem and you're consulting the docs, take a look at the
<a href="#frequentlyaskedquestions">frequently asked questions</a> chapter.)
</p>
<a class="target" name="%E2%80%9Clint?%E2%80%9D"> </a><a class="target" name="writingalintcheck:basics/preliminaries/%E2%80%9Clint?%E2%80%9D"> </a><a class="target" name="toc2.1.1"> </a><h3>“Lint?”</h3>
<p>
The <code>lint</code> tool shipped with the C compiler and provided additional
static analysis of C code beyond what the compiler checked.
</p><p>
Android Lint was named in honor of this tool, and with the Android
prefix to make it really clear that this is a static analysis tool
intended for analysis of Android code, provided by the Android Open
Source Project — and to disambiguate it from the many other tools with
“lint“ in their names.
</p><p>
However, since then, Android Lint has broadened its support and is no
longer intended only for Android code. In fact, within Google, it is
used to analyze all Java and Kotlin code. One of the reasons for this
is that it can easily analyze both Java and Kotlin code without having
to implement the checks twice. Additional features are described in the
<a href="api-guide/../features.html.md">features</a> chapter.
</p><p>
We're planning to rename lint to reflect this new role, so we are
looking for good name suggestions.
</p>
<a class="target" name="apistability"> </a><a class="target" name="writingalintcheck:basics/preliminaries/apistability"> </a><a class="target" name="toc2.1.2"> </a><h3>API Stability</h3>
<p>
Lint's APIs are not stable, and a large part of Lint's API surface is
not under our control (such as UAST and PSI). Therefore, custom lint
checks may need to be updated periodically to keep working.
</p><p>
However, ”some APIs are more stable than others“. In particular, the
detector API (described below) is much less likely to change than the
client API (which is not intended for lint check authors but for tools
integrating lint to run within, such as IDEs and build systems).
</p><p>
However, this doesn't mean the detector API won't change. A large part
of the API surface is external to lint; it's the AST libraries (PSI and
UAST) for Java and Kotlin from JetBrains; it's the bytecode library
(asm.ow2.io), it's the XML DOM library (org.w3c.dom), and so on. Lint
intentionally stays up to date with these, so any API or behavior
changes in these can affect your lint checks.
</p><p>
Lint's own APIs may also change. The current API has grown organically
over the last 10 years (the first version of lint was released in 2011)
and there are a number of things we'd clean up and do differently if
starting over. Not to mention rename and clean up inconsistencies.
</p><p>
However, lint has been pretty widely adopted, so at this point creating
a nicer API would probably cause more harm than good, so we're limiting
recent changes to just the necessary ones. An example of this is the
new <a href="#partialanalysis">partial analysis</a> architecture in 7.0
which is there to allow much better CI and incremental analysis
performance.
</p>
<a class="target" name="kotlin"> </a><a class="target" name="writingalintcheck:basics/preliminaries/kotlin"> </a><a class="target" name="toc2.1.3"> </a><h3>Kotlin</h3>
<p>
We recommend that you implement your checks in Kotlin. Part of
the reason for that is that the lint API uses a number of Kotlin
features:
</p><p>
</p><ul>
<li class="asterisk"><strong class="asterisk">Named and default parameters</strong>: Rather than using builders, some
construction methods, like <code>Issue.create()</code> have a lot of parameters
with default parameters. The API is cleaner to use if you just
specify what you need and rely on defaults for everything else.
<p></p><p>
</p></li>
<li class="asterisk"><strong class="asterisk">Compatibility</strong>: We may add additional parameters over time. It
isn't practical to add @JvmOverloads on everything.
<p></p><p>
</p></li>
<li class="asterisk"><strong class="asterisk">Package-level functions</strong>: Lint's API includes a number of package
level utility functions (in previous versions of the API these are all
thrown together in a <code>LintUtils</code> class).
<p></p><p>
</p></li>
<li class="asterisk"><strong class="asterisk">Deprecations</strong>: Kotlin has support for simple API migrations. For
example, in the below example, the new <code>@Deprecated</code> annotation on
lines 1 through 7 will be added in an upcoming release, to ease
migration to a new API. IntelliJ can automatically quickfix these
deprecation replacements.</li></ul>
<p></p><pre class="listing tilde"><code><div class=" linenumbers"><span class="line"></span><span class="hljs-meta">@Deprecated(
<span class="line"></span> <span class="hljs-meta-string">"Use the new report(Incident) method instead, which is more future proof"</span>,
<span class="line"></span> ReplaceWith(
<span class="line"></span> <span class="hljs-meta-string">"report(Incident(issue, message, location, null, quickfixData))"</span>,
<span class="line"></span> <span class="hljs-meta-string">"com.android.tools.lint.detector.api.Incident"</span>
<span class="line"></span> )</span>
<span class="line"></span>)
<span class="line"></span><span class="hljs-meta">@JvmOverloads</span>
<span class="line"></span><span class="hljs-keyword">open</span> <span class="hljs-function"><span class="hljs-keyword">fun</span> <span class="hljs-title">report</span><span class="hljs-params">(
<span class="line"></span> issue: <span class="hljs-type">Issue</span>,
<span class="line"></span> location: <span class="hljs-type">Location</span>,
<span class="line"></span> message: <span class="hljs-type">String</span>,
<span class="line"></span> quickfixData: <span class="hljs-type">LintFix</span>? = <span class="hljs-literal">null</span>
<span class="line"></span>)</span></span> {
<span class="line"></span> <span class="hljs-comment">// ...</span>
<span class="line"></span>}</div></code></pre><p>
As of 7.0, there is more Kotlin code in lint than remaining Java
code:
</p><div class="table">
<table class="table"><tbody><tr><th style="text-align:left"> Language </th><th style="text-align:right"> files </th><th style="text-align:right"> blank </th><th style="text-align:right"> comment </th><th style="text-align:right"> code </th></tr>
<tr><td style="text-align:left"> Kotlin </td><td style="text-align:right"> 420 </td><td style="text-align:right"> 14243 </td><td style="text-align:right"> 23239 </td><td style="text-align:right"> 130250 </td></tr>
<tr><td style="text-align:left"> Java </td><td style="text-align:right"> 289 </td><td style="text-align:right"> 8683 </td><td style="text-align:right"> 15205 </td><td style="text-align:right"> 101549 </td></tr>
</tbody></table><center><div class="tablecaption"><code>$ cloc lint/</code></div></center></div>
<p></p><p>
And that's for all of lint, including many old lint detectors which
haven't been touched in years. In the Lint API library,
<code>lint/libs/lint-api</code>, the code is 78% Kotlin and 22% Java.
</p>
<a class="target" name="concepts"> </a><a class="target" name="writingalintcheck:basics/concepts"> </a><a class="target" name="toc2.2"> </a><h2>Concepts</h2>
<p>
Lint will search your source code for problems. There are many types of
problems, and each one is called an <code>Issue</code>, which has associated
metadata like a unique id, a category, an explanation, and so on.
</p><p>
Each instance that it finds is called an ”incident“.
</p><p>
The actual responsibility of searching for and reporting incidents is
handled by detectors — subclasses of <code>Detector</code>. Your lint check will
extend <code>Detector</code>, and when it has found a problem, it will ”report“
the incident to lint.
</p><p>
A <code>Detector</code> can analyze more than one <code>Issue</code>. For example, the
built-in <code>StringFormatDetector</code> analyzes formatting strings passed to
<code>String.format()</code> calls, and in the process of doing that discovers
multiple unrelated issues — invalid formatting strings, formatting
strings which should probably use the plurals API instead, mismatched
types, and so on. The detector could simply have a single issue called
“StringFormatProblems” and report everything as a StringFormatProblem,
but that's not a good idea. Each of these individual types of String
format problems should have their own explanation, their own category,
their own severity, and most importantly should be individually
configurable by the user such that they can disable or promote one of
these issues separately from the others.
</p><p>
A <code>Detector</code> can indicate which sets of files it cares about. These are
called “scopes”, and the way this works is that when you register your
<code>Issue</code>, you tell that issue which <code>Detector</code> class is responsible for
analyzing it, as well as which scopes the detector cares about.
</p><p>
If for example a lint check wants to analyze Kotlin files, it can
include the <code>Scope.JAVA_FILE</code> scope, and now that detector will be
included when lint processes Java or Kotin files.
</p><p>
</p><div class="admonition tip">The name <code>Scope.JAVA_FILE</code> may make it sound like there should also
be a <code>Scope.KOTLIN_FILE</code>. However, <code>JAVA_FILE</code> here really refers to
both Java and Kotlin files since the analysis and APIs are identical
for both (using “UAST”, a universal abstract syntax tree). However,
at this point we don't want to rename it since it would break a lot
of existing checks. We might introduce an alias and deprecate this
one in the future.</div>
<p></p><p>
When detectors implement various callbacks, they can analyze the
code, and if they find a problematic pattern, they can “report”
the incident. This means computing an error message, as well as
a “location”. A “location” for an incident is really an error
range — a file, and a starting offset and an ending offset. Locations
can also be linked together, so for example for a “duplicate
declaration” error, you can and should include both locations.
</p><p>
Many detector methods will pass in a <code>Context</code>, or a more specific
subclass of <code>Context</code> such as <code>JavaContext</code> or <code>XmlContext</code>. This
allows lint to provide access to the detectors information they may
need, without passing in a lot of parameters (and allowing lint to add
additional data over time without breaking signatures).
</p><p>
The <code>Context</code> classes also provide many convenience APIs. For example,
for <code>XmlContext</code> there are methods for creating locations for XML tags,
XML attributes, just the name part of an XML attribute and just the
value part of an XML attribute. For a <code>JavaContext</code> there are also
methods for creating locations, such as for a method call, including
whether to include the receiver and/or the argument list.
</p><p>
When you report an <code>Incident</code> you can also provide a <code>LintFix</code>; this is
a quickfix which the IDE can use to offer actions to take on the
warning. In some cases, you can offer a complete and correct fix (such
as removing an unused element). In other cases the fix may be less
clear; for example, the <code>AccessibilityDetector</code> asks you to set a
description for images; the quickfix will set the content attribute,
but will leave the text value as TODO and will select the string such
that the user can just type to replace it.
</p><p>
</p><div class="admonition tip">When reporting incidents, make sure that the error messages are not
generic; try to be explicit and include specifics for the current
scenario. For example, instead of just “Duplicate declaration”, use
“<code>$name</code> has already been declared”. This isn't just for cosmetics;
it also makes lint's <a href="#baselines">baseline
mechanism</a> work better since it
currently matches by id + file + message, not by line numbers which
typically drift over time.</div>
<p></p>
<a class="target" name="clientapiversusdetectorapi"> </a><a class="target" name="writingalintcheck:basics/clientapiversusdetectorapi"> </a><a class="target" name="toc2.3"> </a><h2>Client API versus Detector API</h2>
<p>
Lint's API has two halves:
</p><p>
</p><ul>
<li class="minus">The <strong class="asterisk">Client API</strong>: “Integrate (and run) lint from within a tool”.
For example, both the IDE and the build system uses this API to embed
and invoke lint to analyze the code in the project or editor.
<p></p><p>
</p></li>
<li class="minus">The <strong class="asterisk">Detector API</strong>: “Implement a new lint check”. This is the API
which lets checkers analyze code and report problems that they find.</li></ul>
<p></p><p>
The class in the Client API which represents lint running in a tool is
called <code>LintClient</code>. This class is responsible for, among other things:
</p><p>
</p><ul>
<li class="asterisk">Reporting incidents found by detectors. For example, in the IDE, it
will place error markers into the source editor, and in a build
system, it may write warnings to the console or generate a report or
even fail the build.
<p></p><p>
</p></li>
<li class="asterisk">Handling I/O. Detectors should never read files from disk directly.
This allows lint checks to work smoothly in for example the IDE. When
lint runs on the fly, and a lint check asks for the source file
contents (or other supporting files), the <code>LintClient</code> in the IDE
will implement the <code>readFile</code> method to first look in the open source
editors and if the requested file is being edited, it will return the
current (often unsaved!) contents.
<p></p><p>
</p></li>
<li class="asterisk">Handling network traffic. Lint checks should never open
URLConnections themselves. By going through the lint API to request
data for a URL, not only can the LintClient for example use any
configured IDE proxy settings which is done in the IntelliJ
integration of lint, but even the lint check's own unit tests can
easily be tested because the special unit test implementation of a
<code>LintClient</code> provides a simple way to provide exact responses for
specific URLs:</li></ul>
<p></p><pre class="listing tilde"><code><span class="line"></span>lint()
<span class="line"></span> .files(...)
<span class="line"></span> // Set up exactly the expected maven.google.com network output to
<span class="line"></span> // ensure stable version suggestions in the tests
<span class="line"></span> .networkData("https://maven.google.com/master-index.xml", ""
<span class="line"></span> + "<span class="hljs-comment"><!--?xml version='1.0' encoding='UTF-8'?--></span>\n"
<span class="line"></span> + "<span class="hljs-tag"><<span class="hljs-name">metadata</span>></span>\n"
<span class="line"></span> + " <span class="hljs-tag"><<span class="hljs-name">com.android.tools.build</span>></span>"
<span class="line"></span> + "<span class="hljs-tag"></<span class="hljs-name">com.android.tools.build</span>></span><span class="hljs-tag"></<span class="hljs-name">metadata</span>></span>")
<span class="line"></span> .networkData("https://maven.google.com/com/android/tools/build/group-index.xml", ""
<span class="line"></span> + "<span class="hljs-comment"><!--?xml version='1.0' encoding='UTF-8'?--></span>\n"
<span class="line"></span> + "<span class="hljs-tag"><<span class="hljs-name">com.android.tools.build</span>></span>\n"
<span class="line"></span> + " <span class="hljs-tag"><<span class="hljs-name">gradle</span> <span class="hljs-attr">versions</span>=<span class="hljs-string">"\"</span><span class="hljs-attr">2.3.3</span>,<span class="hljs-attr">3.0.0-alpha1</span>\"/"></span>\n"
<span class="line"></span> + "<span class="hljs-tag"></<span class="hljs-name">gradle</span>></span><span class="hljs-tag"></<span class="hljs-name">com.android.tools.build</span>></span>")
<span class="line"></span>.run()
<span class="line"></span>.expect(...)</code></pre><p>
And much, much, more. <strong class="asterisk">However, most of the implementation of
<code>LintClient</code> is intended for integration of lint itself, and as a check
author you don't need to worry about it.</strong> It's the detector API that
matters, and is also less likely to change than the client API.
</p><p>
</p><div class="admonition tip">The division between the two halves is not perfect; some classes
do not fit neatly in between the two or historically were put in
the wrong place, so this is a high level design to be aware of but
which is not absolute.</div>
<p></p><p>
Also,
</p><p>
</p><div class="admonition warning">Because of the division between two separate packages, which in
retrospect was a mistake, a number of APIs that are only intended
for internal lint usage have been made <code>public</code> such that lint's
code in one package can access it from the other. There's normally a
comment explaining that this is for internal use only, but be aware
that just because something is <code>public</code> or not <code>final</code> it's a good
idea to call or override it.</div>
<p></p>
<a class="target" name="creatinganissue"> </a><a class="target" name="writingalintcheck:basics/creatinganissue"> </a><a class="target" name="toc2.4"> </a><h2>Creating an Issue</h2>
<p>
For information on how to set up the project and to actually publish
your lint checks, see the <a href="#example:samplelintcheckgithubproject">sample</a> and
<a href="#publishingalintcheck">publishing</a> chapters.
</p><p>
<code>Issue</code> is a final class, so unlike <code>Detector</code>, you don't subclass
it, you instantiate it via <code>Issue.create</code>.
</p><p>
By convention, issues are registered inside the companion object of the
corresponding detector, but that is not required.
</p><p>
Here's an example:
</p><pre class="listing tilde"><code><div class=" linenumbers"><span class="line"></span><span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">SdCardDetector</span> : <span class="hljs-type">Detector</span></span>(), SourceCodeScanner {
<span class="line"></span> <span class="hljs-keyword">companion</span> <span class="hljs-keyword">object</span> Issues {
<span class="line"></span> <span class="hljs-meta">@JvmField</span>
<span class="line"></span> <span class="hljs-keyword">val</span> ISSUE = Issue.create(
<span class="line"></span> id = <span class="hljs-string">"SdCardPath"</span>,
<span class="line"></span> briefDescription = <span class="hljs-string">"Hardcoded reference to `/sdcard`"</span>,
<span class="line"></span> explanation = <span class="hljs-string">"""
<span class="line"></span> Your code should not reference the `/sdcard` path directly; \
<span class="line"></span> instead use `Environment.getExternalStorageDirectory().getPath()`.
<span class="line"></span>
<span class="line"></span> Similarly, do not reference the `/data/data/` path directly; it \
<span class="line"></span> can vary in multi-user scenarios. Instead, use \
<span class="line"></span> `Context.getFilesDir().getPath()`.
<span class="line"></span> """</span>,
<span class="line"></span> moreInfo = <span class="hljs-string">"https://developer.android.com/training/data-storage#filesExternal"</span>,
<span class="line"></span> category = Category.CORRECTNESS,
<span class="line"></span> severity = Severity.WARNING,
<span class="line"></span> androidSpecific = <span class="hljs-literal">true</span>,
<span class="line"></span> implementation = Implementation(
<span class="line"></span> SdCardDetector::<span class="hljs-keyword">class</span>.java,
<span class="line"></span> Scope.JAVA_FILE_SCOPE
<span class="line"></span> )
<span class="line"></span> )
<span class="line"></span> }
<span class="line"></span> ...</div></code></pre><p>
There are a number of things to note here.
</p><p>
On line 4, we have the <code>Issue.create()</code> call. We store the issue into a
property such that we can reference this issue both from the
<code>IssueRegistry</code>, where we provide the <code>Issue</code> to lint, and also in the
<code>Detector</code> code where we report incidents of the issue.
</p><p>
Note that <code>Issue.create</code> is a method with a lot of parameters (and we
will probably add more parameters in the future). Therefore, it's a
good practice to explicitly include the argument names (and therefore
to implement your code in Kotlin).
</p><p>
The <code>Issue</code> provides metadata about a type of problem.
</p><p>
The <strong class="asterisk"><code>id</code></strong> is a short, unique identifier for this issue. By
convention it is a combination of words, capitalized camel case (though
you can also add your own package prefix as in Java packages). Note
that the id is “user visible”; it is included in text output when lint
runs in the build system, such as this:
</p><pre class="listing backtick"><code><span class="line"></span>src/main/kotlin/test/pkg/MyTest.kt:4: Warning: Do not hardcode "/sdcard/";
<span class="line"></span> use Environment.getExternalStorageDirectory().getPath() instead [SdCardPath]
<span class="line"></span> val s: String = "/sdcard/mydir"
<span class="line"></span> -------------
<span class="line"></span>0 errors, 1 warnings</code></pre><p>
(Notice the <code>[SdCardPath]</code> suffix at the end of the error message.)
</p><p>
The reason the id is made known to the user is that the ID is how
they'll configure and/or suppress issues. For example, to suppress the
warning in the current method, use
</p><pre class="listing backtick"><code><span class="line"></span><span class="hljs-meta">@Suppress(<span class="hljs-params"><span class="hljs-string">"SdCardPath"</span></span>)</span></code></pre><p>
(or in Java, @SuppressWarnings). Note that there is an IDE quickfix to
suppress an incident which will automatically add these annotations, so
you don't need to know the ID in order to be able to suppress an
incident, but the ID will be visible in the annotation that it
generates, so it should be reasonably specific.
</p><p>
Also, since the namespace is global, try to avoid picking generic names
that could clash with others, or seem to cover a larger set of issues
than intended. For example, “InvalidDeclaration” would be a poor id
since that can cover a lot of potential problems with declarations
across a number of languages and technologies.
</p><p>
Next, we have the <strong class="asterisk"><code>briefDescription</code></strong>. You can think of this as a
“category report header“; this is a static description for all
incidents of this type, so it cannot include any specifics. This string
is used for example as a header in HTML reports for all incidents of
this type, and in the IDE, if you open the Inspections UI, the various
issues are listed there using the brief descriptions.
</p><p>
The <strong class="asterisk"><code>explanation</code></strong> is a multi line, ideally multi-paragraph
explanation of what the problem is. In some cases, the problem is self
evident, as in the case of ”Unused declaration“, but in many cases, the
issue is more subtle and might require additional explanation,
particularly for what the developer should <strong class="asterisk">do</strong> to address the
problem. The explanation is included both in HTML reports and in the
IDE inspection results window.
</p><p>
Note that even though we're using a raw string, and even though the
string is indented to be flush with the rest of the issue registration
for better readability, we don't need to call <code>trimIndent()</code> on
the raw string. Lint does that automatically.
</p><p>
However, we do need to add line continuations — those are the trailing
\'s at the end of the lines.
</p><p>
Note also that we have a Markdown-like simple syntax, described in the
“TextFormat” section below. You can use asterisks for italics or double
asterisks for bold, you can use apostrophes for code font, and so on.
In terminal output this doesn't make a difference, but the IDE,
explanations, incident error messages, etc, are all formatted using
these styles.
</p><p>
The <strong class="asterisk"><code>category</code></strong> isn't super important; the main use is that category
names can be treated as id's when it comes to issue configuration; for
example, a user can turn off all internationalization issues, or run
lint against only the security related issues. The category is also
used for locating related issues in HTML reports. If none of the
built-in categories are appropriate you can also create your own.
</p><p>
The <strong class="asterisk"><code>severity</code></strong> property is very important. An issue can be either a
warning or an error. These are treated differently in the IDE (where
errors are red underlines and warnings are yellow highlights), and in
the build system (where errors can optionally break the build and
warnings do not). There are some other severities too; ”fatal“ is like
error except these checks are designated important enough (and have
very few false positives) such that we run them during release builds,
even if the user hasn't explicitly run a lint target. There's also
“informational” severity, which is only used in one or two places, and
finally the “ignore” severity. This is never the severity you register
for an issue, but it's part of the severities a developer can configure
for a particular issue, thereby turning off that particular check.
</p><p>
You can also specify a <strong class="asterisk"><code>moreInfo</code></strong> URL which will be included in the
issue explanation as a “More Info” link to open to read more details
about this issue or underlying problem.
</p>
<a class="target" name="textformat"> </a><a class="target" name="writingalintcheck:basics/textformat"> </a><a class="target" name="toc2.5"> </a><h2>TextFormat</h2>
<p>
All error messages and issue metadata strings in lint are interpreted
using simple Markdown-like syntax:
</p><div class="table">
<table class="table"><tbody><tr><th style="text-align:left"> Raw text format </th><th style="text-align:left"> Renders To </th></tr>
<tr><td style="text-align:left"> This is a `code symbol` </td><td style="text-align:left"> This is a <code>code symbol</code> </td></tr>
<tr><td style="text-align:left"> This is <code>*italics*</code> </td><td style="text-align:left"> This is <em class="asterisk">italics</em> </td></tr>
<tr><td style="text-align:left"> This is <code>**bold**</code> </td><td style="text-align:left"> This is <strong class="asterisk">bold</strong> </td></tr>
<tr><td style="text-align:left"> <a href="http://," class="url">http://,</a> <a href="https:// " class="url">https:// </a></td><td style="text-align:left"> <a href="http://"></a><a href="http://</a" class="url">http://, </a><a href="https://"></a><a href="https://</a" class="url">https:// </a></td></tr>
<tr><td style="text-align:left"> <code>\*not italics*</code> </td><td style="text-align:left"> <code>\*not italics*</code> </td></tr>
<tr><td style="text-align:left"> ```language\n text\n``` </td><td style="text-align:left"> (preformatted text block) </td></tr>
</tbody></table><center><div class="tablecaption">Supported markup in lint's markdown-like raw text format</div></center></div>
<p></p><p>
This is useful when error messages and issue explanations are shown in
HTML reports generated by Lint, or in the IDE, where for example the
error message tooltips will use formatting.
</p><p>
In the API, there is a <code>TextFormat</code> enum which encapsulates the
different text formats, and the above syntax is referred to as
<code>TextFormat.RAW</code>; it can be converted to <code>.TEXT</code> or <code>.HTML</code> for
example, which lint does when writing text reports to the console or
HTML reports to files respectively. As a lint check author you don't
need to know this (though you can for example with the unit testing
support decide which format you want to compare against in your
expected output), but the main point here is that your issue's brief
description, issue explanation, incident report messages etc, should
use the above “raw” syntax. Especially the first conversion; error
messages often refer to class names and method names, and these should
be surrounded by apostrophes.
</p><p>
See the <a href="#errormessageconventions">error message</a> chapter for more information
on how to craft error messages.
</p>
<a class="target" name="issueimplementation"> </a><a class="target" name="writingalintcheck:basics/issueimplementation"> </a><a class="target" name="toc2.6"> </a><h2>Issue Implementation</h2>
<p>
The last issue registration property is the <strong class="asterisk"><code>implementation</code></strong>. This
is where we glue our metadata to our specific implementation of an
analyzer which can find instances of this issue.
</p><p>
Normally, the <code>Implementation</code> provides two things:
</p><p>
</p><ul>
<li class="asterisk">The <code>.class</code> for our <code>Detector</code> which should be instantiated. In the
code sample above it was <code>SdCardDetector</code>.
<p></p><p>
</p></li>
<li class="asterisk">The <code>Scope</code> that this issue's detector applies to. In the above
example it was <code>Scope.JAVA_FILE</code>, which means it will apply to Java
and Kotlin files.</li></ul>
<p></p>
<a class="target" name="scopes"> </a><a class="target" name="writingalintcheck:basics/scopes"> </a><a class="target" name="toc2.7"> </a><h2>Scopes</h2>
<p>
The <code>Implementation</code> actually takes a <strong class="asterisk">set</strong> of scopes; we still refer
to this as a “scope”. Some lint checks want to analyze multiple types
of files. For example, the <code>StringFormatDetector</code> will analyze both the
resource files declaring the formatting strings across various locales,
as well as the Java and Kotlin files containing <code>String.format</code> calls
referencing the formatting strings.
</p><p>
There are a number of pre-defined sets of scopes in the <code>Scope</code>
class. <code>Scope.JAVA_FILE_SCOPE</code> is the most common, which is a
singleton set containing exactly <code>Scope.JAVA_FILE</code>, but you
can always create your own, such as for example
</p><pre class="listing backtick"><code><span class="line"></span> <span class="hljs-selector-tag">EnumSet</span><span class="hljs-selector-class">.of</span>(Scope.CLASS_FILE, Scope.JAVA_LIBRARIES)</code></pre><p>
When a lint issue requires multiple scopes, that means lint will
<strong class="asterisk">only</strong> run this detector if <strong class="asterisk">all</strong> the scopes are available in the
running tool. When lint runs a full batch run (such as a Gradle lint
target or a full “Inspect Code“ in the IDE), all scopes are available.
</p><p>
However, when lint runs on the fly in the editor, it only has access to
the current file; it won't re-analyze <em class="asterisk">all</em> files in the project for
every few keystrokes. So in this case, the scope in the lint driver
only includes the current source file's type, and only lint checks
which specify a scope that is a subset would run.
</p><p>
This is a common mistake for new lint check authors: the lint check
works just fine as a unit test, but they don't see working in the IDE
because the issue implementation requests multiple scopes, and <strong class="asterisk">all</strong>
have to be available.
</p><p>
Often, a lint check looks at multiple source file types to work
correctly in all cases, but it can still identify <em class="asterisk">some</em> problems given
individual source files. In this case, the <code>Implementation</code> constructor
(which takes a vararg of scope sets) can be handed additional sets of
scopes, called ”analysis scopes“. If the current lint client's scope
matches or is a subset of any of the analysis scopes, then the check
will run after all.
</p>
<a class="target" name="registeringtheissue"> </a><a class="target" name="writingalintcheck:basics/registeringtheissue"> </a><a class="target" name="toc2.8"> </a><h2>Registering the Issue</h2>
<p>
Once you've created your issue, you need to provide it from
an <code>IssueRegistry</code>.
</p><p>
Here's an example <code>IssueRegistry</code>:
</p><pre class="listing tilde"><code><div class=" linenumbers"><span class="line"></span><span class="hljs-keyword">package</span> com.example.lint.checks
<span class="line"></span>
<span class="line"></span><span class="hljs-keyword">import</span> com.android.tools.lint.client.api.IssueRegistry
<span class="line"></span><span class="hljs-keyword">import</span> com.android.tools.lint.client.api.Vendor
<span class="line"></span><span class="hljs-keyword">import</span> com.android.tools.lint.detector.api.CURRENT_API
<span class="line"></span>
<span class="line"></span><span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">SampleIssueRegistry</span> : <span class="hljs-type">IssueRegistry</span></span>() {
<span class="line"></span> <span class="hljs-keyword">override</span> <span class="hljs-keyword">val</span> issues = listOf(SdCardDetector.ISSUE)
<span class="line"></span>
<span class="line"></span> <span class="hljs-keyword">override</span> <span class="hljs-keyword">val</span> api: <span class="hljs-built_in">Int</span>
<span class="line"></span> <span class="hljs-keyword">get</span>() = CURRENT_API
<span class="line"></span>
<span class="line"></span> <span class="hljs-comment">// works with Studio 4.1 or later; see</span>
<span class="line"></span> <span class="hljs-comment">// com.android.tools.lint.detector.api.Api / ApiKt</span>
<span class="line"></span> <span class="hljs-keyword">override</span> <span class="hljs-keyword">val</span> minApi: <span class="hljs-built_in">Int</span>
<span class="line"></span> <span class="hljs-keyword">get</span>() = <span class="hljs-number">8</span>
<span class="line"></span>
<span class="line"></span> <span class="hljs-comment">// Requires lint API 30.0+; if you're still building for something</span>
<span class="line"></span> <span class="hljs-comment">// older, just remove this property.</span>
<span class="line"></span> <span class="hljs-keyword">override</span> <span class="hljs-keyword">val</span> vendor: Vendor = Vendor(
<span class="line"></span> vendorName = <span class="hljs-string">"Android Open Source Project"</span>,
<span class="line"></span> feedbackUrl = <span class="hljs-string">"https://com.example.lint.blah.blah"</span>,
<span class="line"></span> contact = <span class="hljs-string">"[email protected]"</span>
<span class="line"></span> )
<span class="line"></span>}</div></code></pre><p>
On line 8, we're returning our issue. It's a list, so an
<code>IssueRegistry</code> can provide multiple issues.
</p><p>