Add support for highlights notification

pkg/analyzer_plugin/doc/tutorial/highlights.md

Index: pkg/analyzer_plugin/doc/tutorial/highlights.md
diff --git a/pkg/analyzer_plugin/doc/tutorial/highlights.md b/pkg/analyzer_plugin/doc/tutorial/highlights.md
new file mode 100644
index 0000000000000000000000000000000000000000..1bafbda2c20e82a9f90902a43ef5cdd7a4d79a9b
--- /dev/null
+++ b/pkg/analyzer_plugin/doc/tutorial/highlights.md
@@ -0,0 +1,89 @@
+# Providing Highlighting Information
+
+Highlighting information is used by clients to help users identify different
+syntactic and semantic regions of their code.
+
+Syntactic highlighting is highlighting that is based completely on the syntax of
+the code. For example, editors will often provide unique colors for comments,
+string literals, and numeric literals.
+
+Semantic highlighting is highlighting that is based on semantic information. For
+example, an editor could highlight references to fields differently than
+references to local variables. Editors could also highlight references to
+deprecated elements differently.
+
+## Implementation details
+
+Highlighting information is available through a subscription. If the server has
+subscribed for highlighting information in some set of files, then the plugin
+should send the information in an `analysis.highlights` notification whenever
+the information needs to be updated.
+
+When a notification needs to be sent, the method `sendHighlightsNotification`
+will be invoked. This method is responsible for sending the notification.
+
+The easiest way to add support for this notification is by adding the classes
+`HighlightsMixin` and `DartHighlightsMixin` (from
+`package:analyzer_plugin/plugin/highlights_mixin.dart`) to the list of mixins
+for your subclass of `ServerPlugin`. This will leave you with one abstract
+method that you need to implement: `getHighlightsContributors`. That method is
+responsible for returning a list of `HighlightsContributor`s. It is the
+highlights contributors that produce the actual highlighting information. (Most
+plugins will only need a single highlights contributor.)
+
+To write a highlights contributor, create a class that implements
+`HighlightsContributor`. The interface defines a single method named
+`computeHighlights`. The method has two arguments: an `HighlightsRequest` that
+describes the file for which highlighting information is being requested and an
+`HighlightsCollector` through which highlighting information is to be added.
+
+If you mix in the class `DartHighlightsMixin`, then the request will be an
+instance of `DartHighlightsRequest`, which also has analysis results.
+
+## Example
+
+Start by creating a class that implements `HighlightsContributor`, then
+implement the method `computeOutline`. This method is typically implemented

[scheglov, 2017/08/25 16:15:42]

Not Outline.

[Brian Wilkerson, 2017/08/25 16:21:24]

Done

+by creating a visitor (such as an AstVisitor) that can visit the results of the
+analysis (such as a CompilationUnit) and extract the highlighting information
+from the analysis result.
+
+For example, your contributor might look something like the following:
+
+```dart
+class MyHighlightsContributor implements HighlightsContributor {
+  @override
+  void computeHighlights(
+      HighlightsRequest request, HighlightsCollector collector) {
+    if (request is DartHighlightsRequest) {
+      HighlightsVisitor visitor = new HighlightsVisitor(collector);
+      request.result.unit.accept(visitor);
+    }
+  }
+}
+
+class HighlightsVisitor extends RecursiveAstVisitor {
+  final HighlightsCollector collector;
+
+  HighlightsVisitor(this.collector);
+
+  @override
+  void visitSimpleIdentifier(ClassDeclaration node) {
+    // ...
+  }
+}
+```
+
+Given a contributor like the one above, you can implement your plugin similar to
+the following:
+
+```dart
+class MyPlugin extends ServerPlugin with HighlightsMixin, DartHighlightsMixin {
+  // ...
+
+  @override
+  List<HighlightsContributor> getHighlightsContributors(String path) {
+    return <HighlightsContributor>[new MyHighlightsContributor()];
+  }
+}
+```