Update analyzer readme

pkg/analyzer/README.md

-This code is part of an experimental port of the Editor's analysis engine from
-Java to Dart. While we will continue to support the Java version of the analysis
-engine and the services built on it, we also intend to provide the same services
-to Dart-based applications. This is very early code and we expect it to change,
-possibly in significant ways. While we are eager to see other people make use
-of the analysis engine, we also want to be clear, in case you are interested in
-doing so, that the current API's should in no way be considered to be stable.
+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.
 
-In particular, this code was automatically translated from the Java
-implementation. The Java implementation that was translated is still under
-development and will continue to change over time. The translator that was used
-is still under development and the output produced by the translator will change
-over time. Therefore, the API presented by this code will change. In addition,
-any edits made to this code will be overwritten the next time we re-generate
-this code.
+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.

[sethladd, 2015/04/09 16:37:42]

Can you link to the analysis server? How does one use it or learn more about it?

[Brian Wilkerson, 2015/04/09 19:11:52]

I can link to the API spec, but it doesn't do a good job of describing how to
get started. I'd kind of like to leave the work of writing that piece until we
publish the package.

I've added some verbiage to hopefully cover until then.

+The analysis server is currently shipping as an executable in the SDK and will

[scheglov, 2015/04/09 18:18:29]

Hm... "is being currently shipped" or "is currently shipped" maybe?

[Brian Wilkerson, 2015/04/09 19:11:52]

Done

+be released as a package in the near future.
 
-If you are interested in using this code, despite the disclaimer above,
-fantastic! Please let the editor team know so that we can get a sense of the
-interest in it. Also, feel free to ask questions and make requests for
-additional functionality.
+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,
+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 https://code.google.com/p/dart/issues or by

[sethladd, 2015/04/09 16:37:42]

Let's use markdown's linking capabilities.

[Brian Wilkerson, 2015/04/09 19:11:52]

I took a stab at it, but don't have a way to preview to see whether I'm doing it
right.

+emailing analyzer-discuss@dartlang.org.