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