| Index: packages/analyzer/README.md
|
| diff --git a/packages/analyzer/README.md b/packages/analyzer/README.md
|
| index eb5c89ea9c1152b22b310d2b10999f4ef1f86808..6915a5854971f70ad7a76df8785376d183775417 100644
|
| --- a/packages/analyzer/README.md
|
| +++ b/packages/analyzer/README.md
|
| @@ -1,27 +1,113 @@
|
| -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).
|
| -
|
| -The API's in this package are, quite frankly, a mess at the moment. They were
|
| +# 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][].
|
| +
|
| +## Configuring the analyzer
|
| +
|
| +Both `dartanalyzer` and Dart Analysis Server can be configured with either an
|
| +`analysis_options.yaml` or `.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 (for example,
|
| +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:
|
| +
|
| +```yaml
|
| +analyzer:
|
| + exclude:
|
| + - test/_data/p4/lib/lib1.dart
|
| + - test/_data/p5/p5.dart
|
| + - test/_data/bad*.dart
|
| + - test/_brokendata/**
|
| +```
|
| +
|
| +Note that you can use globs, as defined by the [glob package][glob].
|
| +
|
| +Here is an example file that enables the analyzer's [strong mode][strongmode]:
|
| +
|
| +```yaml
|
| +analyzer:
|
| + strong-mode: true
|
| +```
|
| +
|
| +Here is an example file that enables two lint rules:
|
| +
|
| +```yaml
|
| +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:
|
| +
|
| +```yaml
|
| +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][analysis_sever] - a stateful server that supports IDEs and editors
|
| +
|
| +## Support
|
| +
|
| +Post issues and feature requests at https://github.com/dart-lang/sdk/issues
|
| +
|
| +Questions and discussions are welcome at the
|
| +[Dart Analyzer Discussion Group][list].
|
| +
|
| +## Background
|
| +
|
| +The APIs 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,
|
| +APIs. 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]: https://htmlpreview.github.io/?https://github.com/dart-lang/sdk/blob/master/pkg/analysis_server/doc/api.html
|
| +[analyzercli]: https://github.com/dart-lang/sdk/tree/master/pkg/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
|
| +[glob]: https://pub.dartlang.org/packages/glob
|
| +[LICENSE]: https://github.com/dart-lang/sdk/blob/master/pkg/analyzer/LICENSE
|
| +[dartfmt]: https://github.com/dart-lang/dart_style
|
| +[dartdoc]: https://github.com/dart-lang/dartdoc
|
| +[analysis_sever]: https://github.com/dart-lang/sdk/tree/master/pkg/analysis_server
|
|
|