document analysis_options

pkg/analyzer/README.md

-The analysis package defines support for performing static analysis of Dart
-code. It was designed to support tooling efforts, but has also been used for
-such things as statistics gathering and code transformers.
+# Analyzer for Dart
 
-If you are interested in providing Dart support in a long-running tool, such as
-an editor or IDE, you should use the analysis server instead of this package.
-The analysis server is currently shipped as an executable in the SDK and will
-be released as a package in the near future. In the meantime, if you'd like to
-learn more about it, please look at the
-[Analysis Server API Specification](http://htmlpreview.github.io/?https://github.com/dart-lang/sdk/blob/master/pkg/analysis_server/doc/api.html)
-or contact the mailing list (see below).
+This package provides a low-level _library_ that performs static analysis
+of Dart code. It is useful for tool
+integration and embedding.
+
+End-users should use the [dartanalyzer][analyzercli] command-line tool
+to analyze their Dart code.
+
+Integrators that want to add Dart support to their editor
+should use the _Dart Analysis Server_.
+The [Analysis Server API Specification][serverapi] is available.
+If you are adding Dart support to an editor or IDE, please let us know
+by emailing our [list][].
+
+## Configuring the analyzer
+
+Both the dartanalyzer and Dart Analysis Server can be configured
+with a `.analysis_options` file. This YAML file can control which files
+and paths are analyzed, which lints are applied, and more.

[Brian Wilkerson, 2015/10/20 00:16:41]

Last I checked (a couple of days ago), lints were not completely connected
end-to-end. I would remove discussion of them until they're complete.

[sethladd, 2015/10/20 18:32:15]

Ah, interesting. How long until they are completed connected?

[Brian Wilkerson, 2015/10/20 18:41:41]

Currently targeted for 1.14.

+
+If you are embedding the analyzer library in your project, you are
+responsible for finding the `.analysis_options` file, parsing it,
+and configuring the analyzer.

[Brian Wilkerson, 2015/10/20 00:16:41]

There is at least one utility class that can help: AnalysisOptionsProvider. It
can read and parse the file once it's been located.

[sethladd, 2015/10/20 18:32:14]

Where is that file? in this analyzer package?

[Brian Wilkerson, 2015/10/20 18:41:41]

pkg/analyzer/lib/source/analysis_options_provider.dart

+
+The `.analysis_options` file should live
+at the root of your project (typically, next to your `pubspec.yaml`).
+Different embedders of analyzer, such as dartanalyzer or Dart Analysis Server,
+may choose to find the file in various different ways. Consult their
+documentation to learn more.
+
+Here is an example file that instructs the analyzer
+to ignore two files:
+
+```
+analyzer:
+  exclude:
+    - test/_data/p4/lib/lib1.dart
+    - test/_data/p5/p5.dart
+```
+
+Here is an example file that enables the analyzer's _strong mode_:
+
+```
+analyzer:
+  strong-mode: true
+```
+
+Here is an example file that enables two lint rules:

[Brian Wilkerson, 2015/10/20 00:16:41]

Again, I'd remove this (lines 49-70) for now.

+
+```
+linter:
+  rules:
+    - camel_case_types
+    - empty_constructor_bodies
+```
+
+Check out all the available [Dart lint rules][lintrules].
+
+You can combine the `analyzer` section and the `linter` section into a single
+configuration. Here is an example:
+
+```
+analyzer:
+  exclude:
+    - test/_data/p4/lib/lib1.dart
+linter:
+  rules:
+    - camel_case_types
+```
+
+## Who uses this library?
+
+Many tools embed this library, such as:
+
+* dartfmt - a formatter for Dart code
+* dartdoc - a documentation generator for Dart code
+* Dart Analysis Server - a stateful server that supports IDEs and editors
+
+## Support
+
+Questions and requests for additional functionality are welcome.
+Please open an issue at
+[http://dartbug.com](http://dartbug.com)
+or by email
+[analyzer-discuss@dartlang.org][list].
+
+## Background
 
 The API's in this package are, quite frankly, a mess at the moment. They were
 originally machine generated by a translator and were based on an earlier Java
 implementation. Several of the API's still look like their Java predecessors
 (or worse) rather than clean Dart API's.
 
 In addition, there is currently no clean distinction between public and internal
-API's. We plan to address this issue soon, but doing so will, unfortunately,
+API's. We plan to address this issue but doing so will, unfortunately,
 require a large number of breaking changes. We will try to minimize the pain
 this causes for our clients, but some pain is inevitable.
 
-Questions and requests for additional functionality are welcome, and can be made
-by either opening an issue at
-[http://dartbug.com](http://dartbug.com)
-or by emailing
-[analyzer-discuss@dartlang.org](https://groups.google.com/a/dartlang.org/forum/#!forum/analyzer-discuss).
+## License
+
+See the LICENSE file.
+
+[serverapi]: http://htmlpreview.github.io/?https://github.com/dart-lang/sdk/blob/master/pkg/analysis_server/doc/api.html
+[analyzercli]: https://github.com/dart-lang/analyzer_cli
+[list]: https://groups.google.com/a/dartlang.org/forum/#!forum/analyzer-discuss
+[lintrules]: http://dart-lang.github.io/linter/lints/