Skip to content

Commit f0bbc39

Browse files
michaelpjeddiemundopepeiborramergify[bot]
authored
Rework features documentation (#2603)
* Rework features documentation This does a few things: - Adds a clear listing of which LSP methods we support, and which we don't (requested a couple of times recently). - Lists every code action and code lens, which plugin provies them, their status, and code action kind where applicable (apart from Wingman because there are lots and I couldn't figure it all out). Possibly some of this information belongs elsewhere, e.g. perhaps instead of listing which versions don't have full support on this page, we should instead add a page to the GHC support page that lists which plugins work on which versions. Not sure. * Add a couple of known limitations * Move plugin GHC version support to other page * Purge useless status column * Update docs/features.md Add link to qualify imported names readme * Update docs/features.md * Update docs/features.md * Update docs/features.md * Update docs/features.md * Update docs/features.md i don't know how to use github * Clarify text * Mention limitations of apply-refact Co-authored-by: J. S <[email protected]> Co-authored-by: Pepe Iborra <[email protected]> Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
1 parent b937baa commit f0bbc39

File tree

5 files changed

+275
-36
lines changed

5 files changed

+275
-36
lines changed

‎docs/_static/theme_overrides.css

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
/* Fix table wrapping https://github.com/readthedocs/sphinx_rtd_theme/issues/117 */
2+
@media screen and (min-width: 768px) {
3+
.wy-table-responsive table td, .wy-table-responsive table th {
4+
white-space: normal !important;
5+
}
6+
}

‎docs/conf.py

+6-1
Original file line numberDiff line numberDiff line change
@@ -86,4 +86,9 @@
8686

8787
# Enable linking to an anchor of a relative page
8888
# See https://github.com/executablebooks/MyST-Parser/issues/443
89-
myst_heading_anchors = 2
89+
myst_heading_anchors = 3
90+
91+
# -- Custom Document processing ----------------------------------------------
92+
93+
def setup(app):
94+
app.add_css_file("theme_overrides.css")

‎docs/features.md

+237-35
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,260 @@
11
# Features
22

3-
You can watch demos for some of these features [below](#demos).
4-
5-
- Warning and error diagnostics from GHC
6-
- Type information and documentation on hover, [including your own comments](./configuration.md#how-to-show-local-documentation-on-hover).
7-
- Jump to definition: [for now only for local code definitions](https://github.com/haskell/haskell-language-server/issues/708)
8-
- Document symbols
9-
- Highlight references in document
10-
- Code completion
11-
- Formatting via [Brittany](https://github.com/lspitzner/brittany), [Floskell](https://github.com/ennocramer/floskell), [Fourmolu](https://github.com/fourmolu/fourmolu), [Ormolu](https://github.com/tweag/ormolu) or [Stylish Haskell](https://github.com/haskell/stylish-haskell)
12-
- [Code evaluation](#code-evaluation), see its [Tutorial](https://github.com/haskell/haskell-language-server/blob/master/plugins/hls-eval-plugin/README.md)
13-
- [Integration with](#retrie-integration) [retrie](https://hackage.haskell.org/package/retrie), a powerful, easy-to-use codemodding tool
14-
- [Code lenses for explicit import lists](#explicit-import-lists)
15-
- [Generate functions from type signatures, and intelligently complete holes](#wingman) using [Wingman (tactics)](https://github.com/haskell/haskell-language-server/tree/master/plugins/hls-tactics-plugin)
16-
- [Integration](#hlint) with [hlint](https://github.com/ndmitchell/hlint), the most used haskell linter, to show diagnostics and apply hints via [apply-refact](https://github.com/mpickering/apply-refact)
17-
- [Module name suggestions](#module-names) for insertion or correction
18-
- [Call hierarchy support](#call-hierarchy)
19-
- [Qualify names from an import declaration](#qualify-imported-names) in your code
20-
- [Suggest alternate numeric formats](#alternate-number-formatting)
21-
22-
## Demos
23-
24-
### Code evaluation
3+
This table gives a summary of the features that HLS supports.
4+
Many of these are standard LSP features, but a lot of special features are provided as [code actions](#code-actions) and [code lenses](#code-lenses).
255

26-
![Eval Demo](https://raw.githubusercontent.com/haskell/haskell-language-server/master/plugins/hls-eval-plugin/demo.gif)
6+
| Feature | [LSP method](./what-is-hls.md#lsp-terminology) |
7+
|-----------------------------------------------------|---------------------------------------------------------------------------------------------------|
8+
| [Diagnostics](#diagnostics) | `textDocument/publishDiagnostics` |
9+
| [Hovers](#hovers) | `textDocument/hover` |
10+
| [Jump to definition](#jump-to-definition) | `textDocument/definition` |
11+
| [Jump to type definition](#jump-to-type-definition) | `textDocument/typeDefinition` |
12+
| [Find references](#find-references) | `textDocument/references` |
13+
| [Completions](#completions) | `textDocument/completion` |
14+
| [Formatting](#formatting) | `textDocument/formatting`, `textDocument/rangeFormatting` |
15+
| [Document symbols](#document-symbols) | `textDocument/documentSymbol` |
16+
| [Workspace symbols](#workspace-symbols) | `workspace/symbol` |
17+
| [Call hierarchy](#call-hierarchy) | `textDocument/prepareCallHierarchy`, `callHierarchy/incomingCalls`, `callHierarchy/outgoingCalls` |
18+
| [Highlight references](#highlight-references) | `textDocument/documentHighlight` |
19+
| [Code actions](#code-actions) | `textDocument/codeAction` |
20+
| [Code lenses](#code-lenses) | `textDocument/codeLens` |
2721

28-
### Retrie integration
22+
The individual sections below also identify which [HLS plugin](./what-is-hls.md#hls-plugins) is responsible for providing the given functionality, which is useful if you want to raise an issue report or contribute!
23+
Additionally, not all plugins are supported on all versions of GHC, see the [GHC version support page](supported-versions.md) for details.
2924

30-
![Retrie Demo](https://i.imgur.com/Ev7B87k.gif)
25+
## Diagnostics
3126

32-
### Explicit import lists
27+
### GHC compiler errors and warnings
28+
Provided by: `ghcide`
3329

34-
![Imports code lens Demo](https://imgur.com/pX9kvY4.gif)
30+
Provides errors and warnings from GHC as diagnostics.
3531

36-
### Wingman
32+
### Hlint hints
33+
Provided by: `hls-hlint-plugin`
3734

38-
![Wingman Demo](https://user-images.githubusercontent.com/307223/92657198-3d4be400-f2a9-11ea-8ad3-f541c8eea891.gif)
35+
Provides hlint hints as diagnostics.
3936

40-
### Hlint
37+
## Hovers
38+
Provided by: `ghcide`
4139

42-
![Hlint Demo](https://user-images.githubusercontent.com/54035/110860028-8f9fa900-82bc-11eb-9fe5-6483d8bb95e6.gif)
40+
Type information and documentation on hover, [including from local definitions](./configuration.md#how-to-show-local-documentation-on-hover).
4341

44-
### Module names
42+
## Jump to definition
43+
Provided by: `ghcide`
4544

46-
![Module Name Demo](https://user-images.githubusercontent.com/54035/110860755-78ad8680-82bd-11eb-9845-9ea4b1cc1f76.gif)
45+
Jump to the definition of a name.
46+
47+
Known limitations:
48+
- Only works for [local definitions](https://github.com/haskell/haskell-language-server/issues/708).
49+
50+
## Jump to type definition
51+
Provided by: `ghcide`
52+
53+
Known limitations:
54+
- Only works for [local definitions](https://github.com/haskell/haskell-language-server/issues/708).
55+
56+
## Find references
57+
Provided by: `ghcide`
58+
59+
Find references to a name within the project.
60+
61+
## Completions
62+
63+
### Code completions
64+
Provided by: `ghcide`
65+
66+
- Completion of names from qualified imports.
67+
- Completion of names from non-imported modules.
68+
69+
### Pragma completions
70+
Provided by: `hls-pragmas-plugin`
71+
72+
Completions for language pragmas.
73+
74+
## Formatting
75+
Format your code with various Haskell code formatters.
76+
77+
| Formatter | Provided by |
78+
|-----------------|------------------------------|
79+
| Brittany | `hls-brittany-plugin` |
80+
| Floskell | `hls-floskell-plugin` |
81+
| Fourmolu | `hls-fourmolu-plugin` |
82+
| Ormolu | `hls-ormolu-plugin` |
83+
| Stylish Haskell | `hls-stylish-haskell-plugin` |
84+
85+
## Document symbols
86+
Provided by: `ghcide`
87+
88+
Provides listing of the symbols defined in a module, used to power outline displays.
89+
90+
## Workspace symbols
91+
Provided by: `ghcide`
92+
93+
Provides listing of the symbols defined in the project, used to power searches.
4794

48-
### Call hierarchy
95+
## Call hierarchy
96+
Provided by: `hls-call-hierarchy-plugin`
97+
98+
Shows ingoing and outgoing calls for a function.
4999

50100
![Call Hierarchy in VSCode](https://github.com/haskell/haskell-language-server/raw/2857eeece0398e1cd4b2ffb6069b05c4d2308b39/plugins/hls-call-hierarchy-plugin/call-hierarchy-in-vscode.gif)
51101

102+
## Highlight references
103+
Provided by: `ghcide`
104+
105+
Highlights references to a name in a document.
106+
107+
## Code actions
108+
109+
### Insert missing pragmas
110+
Provided by: `hls-pragma-plugin`
111+
112+
Code action kind: `quickfix`
113+
114+
Inserts missing pragmas needed by GHC.
115+
116+
### Apply Hlint fixes
117+
Provided by: `hls-hlint-plugin`
118+
119+
Code action kind: `quickfix`
120+
121+
Applies hints, either individually or for the whole file.
122+
Uses [apply-refact](https://github.com/mpickering/apply-refact).
123+
124+
![Hlint Demo](https://user-images.githubusercontent.com/54035/110860028-8f9fa900-82bc-11eb-9fe5-6483d8bb95e6.gif)
125+
126+
Known limitations:
127+
- May have strange behaviour in files with CPP, since `apply-refact` does not support CPP.
128+
129+
### Make import lists fully explicit
130+
Provided by: `hls-explicit-imports-plugin`
131+
132+
Code action kind: `quickfix.literals.style`
133+
134+
Make import lists fully explicit (same as the code lens).
135+
52136
### Qualify imported names
137+
Provided by: `hls-qualify-imported-names-plugin`
138+
139+
Code action kind: `quickfix`
140+
141+
Rewrites imported names to be qualified.
53142

54143
![Qualify Imported Names Demo](../plugins/hls-qualify-imported-names-plugin/qualify-imported-names-demo.gif)
144+
145+
For usage see the ![readme](../plugins/hls-qualify-imported-names-plugin/README.md).
146+
147+
### Refine import
148+
Provided by: `hls-refine-imports-plugin`
149+
150+
Code action kind: `quickfix.import.refine`
151+
152+
Refines imports to more specific modules when names are re-exported (same as the code lens).
153+
154+
### Add missing class methods
155+
Provided by: `hls-class-plugin`
55156

56-
### Alternate Number Formatting
157+
Code action kind: `quickfix`
158+
159+
Adds placeholders for missing class methods in a class instance definition.
160+
161+
### Unfold definition
162+
Provided by: `hls-retrie-plugin`
163+
164+
Code action kind: `refactor.extract`
165+
166+
Extracts a definition from the code.
167+
168+
### Fold definition
169+
Provided by: `hls-retrie-plugin`
170+
171+
Code action kind: `refactor.inline`
172+
173+
Inlines a definition from the code.
174+
175+
![Retrie Demo](https://i.imgur.com/Ev7B87k.gif)
176+
177+
### Insert contents of Template Haskell splice
178+
Provided by: `hls-splice-plugin`
179+
180+
Code action kind: `refactor.rewrite`
181+
182+
Evaluates a Template Haskell splice and inserts the resulting code in its place.
183+
184+
### Convert numbers to alternative formats
185+
Provided by: `hls-alternate-number-format-plugin`
186+
187+
Code action kind: `quickfix.literals.style`
188+
189+
Converts numeric literals to different formats.
57190

58191
![Alternate Number Format Demo](../plugins/hls-alternate-number-format-plugin/HLSAll.gif)
192+
193+
### Add Haddock comments
194+
Provided by: `hls-haddock-comments-plugin`
195+
196+
Code action kind: `quickfix`
197+
198+
Adds Haddock comments for function arguments.
199+
200+
### Wingman
201+
Status: Not supported on GHC 9.2
202+
203+
Provided by: `hls-tactics-plugin`
204+
205+
Provides a variety of code actions for interactive code development, see https://haskellwingman.dev/ for more details.
206+
207+
![Wingman Demo](https://user-images.githubusercontent.com/307223/92657198-3d4be400-f2a9-11ea-8ad3-f541c8eea891.gif)
208+
209+
## Code lenses
210+
211+
### Add type signature
212+
Provided by: `ghcide`
213+
214+
Shows the type signature for bindings without type signatures, and adds it with a click.
215+
216+
### Evaluation code snippets in comments
217+
Provided by: `hls-eval-plugin`
218+
219+
Evaluates code blocks in comments with a click. [Tutorial](https://github.com/haskell/haskell-language-server/blob/master/plugins/hls-eval-plugin/README.md).
220+
221+
![Eval Demo](https://raw.githubusercontent.com/haskell/haskell-language-server/master/plugins/hls-eval-plugin/demo.gif)
222+
223+
### Make import lists fully explicit
224+
Provided by: `hls-explicit-imports-plugin`
225+
226+
Shows fully explicit import lists and rewrites them with a click (same as the code action).
227+
228+
![Imports code lens Demo](https://imgur.com/pX9kvY4.gif)
229+
230+
### Refine import
231+
Provided by: `hls-refine-imports-plugin`
232+
233+
Shows refined imports and applies them with a click (same as the code action).
234+
235+
### Fix module names
236+
Provided by: `hls-module-name-plugin`
237+
238+
Shows module name matching file path, and applies it with a click.
239+
240+
![Module Name Demo](https://user-images.githubusercontent.com/54035/110860755-78ad8680-82bd-11eb-9845-9ea4b1cc1f76.gif)
241+
242+
## Missing features
243+
244+
The following features are supported by the LSP specification but not implemented in HLS.
245+
Contributions welcome!
246+
247+
| Feature | Status | [LSP method](./what-is-hls.md#lsp-terminology) |
248+
|------------------------|------------------------------------------------------------------------------------------|-----------------------------------------------------|
249+
| Signature help | Unimplemented | `textDocument/signatureHelp` |
250+
| Jump to declaration | Unclear if useful | `textDocument/declaration` |
251+
| Jump to implementation | Unclear if useful | `textDocument/implementation` |
252+
| Renaming | [Parital implementation](https://github.com/haskell/haskell-language-server/issues/2193) | `textDocument/rename`, `textDocument/prepareRename` |
253+
| Folding | Unimplemented | `textDocument/foldingRange` |
254+
| Selection range | Unimplemented | `textDocument/selectionRange` |
255+
| Semantic tokens | Unimplemented | `textDocument/semanticTokens` |
256+
| Linked editing | Unimplemented | `textDocument/linkedEditingRange` |
257+
| Document links | Unimplemented | `textDocument/documentLink` |
258+
| Document color | Unclear if useful | `textDocument/documentColor` |
259+
| Color presentation | Unclear if useful | `textDocument/colorPresentation` |
260+
| Monikers | Unclear if useful | `textDocument/moniker` |

‎docs/supported-versions.md

+25
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,31 @@ GHC versions not in the list have never been supported by HLS, or are not planne
2626

2727
The policy for when we deprecate support for versions of GHC is given below. The table reflects that, but we may decide to deviate from it for good reasons.
2828

29+
Additionally, some plugins do not have support for some GHC versions, as shown in the following table.
30+
As such, the functionality provided by those plugins is not available in HLS when using a GHC version which they do not support.
31+
32+
| Plugin | Unsupported GHC versions |
33+
|-------------------------------------|--------------------------|
34+
| `hls-alternate-number-plugin` | 9.2 |
35+
| `hls-brittany-plugin` | 9.2 |
36+
| `hls-call-hierarchy-plugin` | |
37+
| `hls-class-plugin` | 9.2 |
38+
| `hls-eval-plugin` | 9.2 |
39+
| `hls-explicit-imports-plugin` | |
40+
| `hls-floskell-plugin` | |
41+
| `hls-fourmolu-plugin` | |
42+
| `hls-haddock-comments-plugin` | 9.2 |
43+
| `hls-hlint-plugin` | 9.2 |
44+
| `hls-module-name-plugin` | |
45+
| `hls-ormolu-plugin` | |
46+
| `hls-pragmas-plugin` | |
47+
| `hls-qualify-imported-names-plugin` | |
48+
| `hls-refine-imports-plugin` | |
49+
| `hls-retrie-plugin` | 9.2 |
50+
| `hls-splice-plugin` | 9.2 |
51+
| `hls-stylish-haskell-plugin` | 9.0, 9.2 |
52+
| `hls-tactics-plugin` | 9.2 |
53+
2954
### Using deprecated GHC versions
3055

3156
Users who want to use a GHC version which is not supported by the latest HLS can still use older versions of HLS (consult the version support table above to identify the appropriate HLS version).

‎docs/what-is-hls.md

+1
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ Here are a few pieces of jargon that you may come across in the HLS docs or when
3333
- *Completion item*: An item that can be inserted into the text, including its metadata.
3434
- *Diagnostic*: Any information about the project that is shown in the editor, including errors, warnings, and hints from tools such as hlint.
3535
- *Semantic highlighting*: Special syntax highlighting performed by the server.
36+
- *Method*: A LSP method is a function in the LSP protocol that the client can invoke to perform some action, e.g. ask for completions at a point.
3637

3738
## haskell-language-server
3839

0 commit comments

Comments
 (0)