Address user confusion about excluding files

[bwilkerson]

Page URL

https://dart.dev/tools/analysis#excluding-files

Page source

No response

Describe the problem

Some users appear to be confused about exactly what it means to exclude a file from analysis using the exclude: key in the analyzer section of the analysis options file. I think some users assume that it means that the analyzer won't open and analyze the file under any conditions, and that's not the case. I think we can address this confusion by expanding the description.

Expected fix

I would propose adding something like the following to the section to clarify the actual impact of including a file in this section.

---

Note that adding a file, or a glob matching a file, to this section doesn't guarantee that the file will not be analyzed. The analyzer will still perform some analysis of excluded files if they are referenced from some other file that's being analyzed or if they are explicitly opened in the IDE.

What it does guarantee is that

• the analyzer won't analyze the file unless it needs to, and
• no diagnostics will be reported for the file.

Even if the analyzer needs to analyze an excluded file it can skip any portions of the normal analysis that aren't necessary.

Additional context

No response

[bwilkerson]

@jacob314 @srawlins