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][].

[pquitslund, 2015/10/20 15:48:01]

Is this shorthand for [list][list]?

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

yup!

+
+## 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.
+
+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.
+
+The `.analysis_options` file should live
+at the root of your project (typically, next to your `pubspec.yaml`).

[Cutch, 2015/10/20 01:10:36]

remove 'typically'

[pquitslund, 2015/10/20 15:48:01]

Just another motivation to formalize (though I'm not sure where) our notion of a
'project'.

Seth: is your intent to allow for the case where folks are using a `.packages`
file and no pubspec?

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

Done.

+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

[Cutch, 2015/10/20 01:10:36]

Show an example of globbing:

- 'test/_data/bad*.dart'

Show an example of recursive globbing:
- 'test/_brokendata/**'

Call out that the glob syntax is defined by the glob package.

[pquitslund, 2015/10/20 15:48:01]

+1.

FWIW: this is enough of a potential snag that I'm going to add validation and
error-reporting to catch this case.

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

Done.

+```
+
+Here is an example file that enables the analyzer's [strong mode][strongmode]:
+
+```
+analyzer:
+  strong-mode: true
+```
+
+Here is an example file that enables two lint rules:
+
+```
+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

[pquitslund, 2015/10/20 15:48:01]

API's => APIs ?

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

Done.

 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,

[pquitslund, 2015/10/20 15:48:01]

API's => APIs ?

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

Done.

 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/
+[strongmode]: https://github.com/dart-lang/dev_compiler/blob/master/STRONG_MODE.md