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>
40 lines
1.6 KiB
Markdown
40 lines
1.6 KiB
Markdown
# Adding Navigation
|
|
|
|
This document describes what navigation is and how to enhance it.
|
|
|
|
## Overview
|
|
|
|
Navigation is the ability to move from one piece of text to a related location.
|
|
This includes such things as jumping to the declaration of an identifier or
|
|
opening a file based on a URI or file path.
|
|
|
|
## Enhancing navigation
|
|
|
|
If we have decided to provide navigation from a given kind of text that was
|
|
previously not supported, you can add that support by modifying the class
|
|
`_DartNavigationComputerVisitor`. That class is a `RecursiveAstVisitor`, so the
|
|
first task is to figure out which kind of node contains the text at the origin.
|
|
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, compute the region from which the user can navigate
|
|
and the location to which they should be navigated. There are some utility
|
|
methods in `_DartNavigationCollector`, to make common cases easier, or you can
|
|
use `computer.collector.addRegion` to add an arbitrary region.
|
|
|
|
## Testing the navigation
|
|
|
|
The tests for navigation are in the class `AnalysisNotificationNavigationTest`.
|
|
|
|
The tests generally follow the following pattern:
|
|
|
|
1. Use `addTestFile` to add a file containing both the origin and target of the
|
|
navigation.
|
|
2. Use `await prepareNavigation();` to compute and cache navigation results.
|
|
3. Use `assertHasRegion` to test that the offset of the string in the test file
|
|
is a navigation origin, and `assertHasTarget` to ensure the target to which
|
|
the user will be navigated.
|