document analysis_options

pkg/analyzer/README.md

Index: pkg/analyzer/README.md
diff --git a/pkg/analyzer/README.md b/pkg/analyzer/README.md
index eb5c89ea9c1152b22b310d2b10999f4ef1f86808..1009bc231263485bb717004c7327f496c285514f 100644
--- a/pkg/analyzer/README.md
+++ b/pkg/analyzer/README.md
@@ -1,14 +1,91 @@
-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.
-
-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).
+# Analyzer for Dart
+
+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
@@ -16,12 +93,16 @@ 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