Brian Wilkerson
e845949df6
Change-Id: Ie836c01d167ec17df9d762a365da278499076e11 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/276181 Reviewed-by: Kallen Tu <kallentu@google.com> Commit-Queue: Brian Wilkerson <brianwilkerson@google.com>
50 lines
2.2 KiB
Markdown
50 lines
2.2 KiB
Markdown
# Adding Semantic Highlighting
|
|
|
|
This document describes what semantic highlighting is and how to enhance it.
|
|
|
|
## Overview
|
|
|
|
Syntactic highlighting is the support that styles tokens in the source code
|
|
based on where those tokens are located in the grammar. For example, syntactic
|
|
highlighting is used to apply a color to all of the keywords and
|
|
pseudo-keywords.
|
|
|
|
Semantic highlighting includes syntactic highlighting, but additionally styles
|
|
tokens based on their semantics. For example, semantic highlighting is used to
|
|
apply a color to type names or a strikethrough to deprecated elements.
|
|
|
|
Note that the analysis server isn't the only implementation of syntactic
|
|
highlighting that the Dart team controls, and all of the implementations should
|
|
be kept reasonably consistent with each other.
|
|
|
|
## Enhancing semantic highlighting
|
|
|
|
If we have decided to change semantic highlighting, you can add that support by
|
|
modifying the class `_DartUnitHighlightsComputerVisitor`. That class is a
|
|
`RecursiveAstVisitor`, so the first task is to figure out which kind of node
|
|
contains the text to be styled. You can then either add a new `visit` method for
|
|
the node or edit an existing method.
|
|
|
|
If you're adding a new `visit` method, you'll need to invoke the overridden
|
|
method to ensure that children are still visited.
|
|
|
|
Within the `visit` method, use one of the private methods on the `computer` to
|
|
associate a highlight region with a `HighlightRegionType`. The mapping from a
|
|
highlight type to actual text styling is handled by the client (and is in some
|
|
cases user controlled).
|
|
|
|
## Testing semantic highlighting
|
|
|
|
The tests for semantic highlighting are in the class
|
|
`AnalysisNotificationHighlightsTest`.
|
|
|
|
The tests generally follow the following pattern:
|
|
|
|
1. Use `addTestFile` to add a file containing code that should be highlighted.
|
|
2. Use `await prepareHighlights();` to compute and cache the semantic
|
|
highlighting results.
|
|
3. Use `assertHasRegion` to test that the expected highlight type is associated
|
|
with the region that matches the search string. If the search string needs to
|
|
be longer than the highlight region in order to be unique, then the optional
|
|
length argument can be provided so specify the expected length of the region.
|