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