# 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.