mirror of
https://github.com/haskell/haskell-language-server.git
synced 2024-09-11 08:45:35 +03:00
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 <document_done@hotmail.com> Co-authored-by: Pepe Iborra <pepeiborra@gmail.com> Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
This commit is contained in:
parent
b937baa03c
commit
f0bbc390b9
6
docs/_static/theme_overrides.css
vendored
Normal file
6
docs/_static/theme_overrides.css
vendored
Normal file
@ -0,0 +1,6 @@
|
||||
/* Fix table wrapping https://github.com/readthedocs/sphinx_rtd_theme/issues/117 */
|
||||
@media screen and (min-width: 768px) {
|
||||
.wy-table-responsive table td, .wy-table-responsive table th {
|
||||
white-space: normal !important;
|
||||
}
|
||||
}
|
@ -86,4 +86,9 @@ html_static_path = ['_static']
|
||||
|
||||
# Enable linking to an anchor of a relative page
|
||||
# See https://github.com/executablebooks/MyST-Parser/issues/443
|
||||
myst_heading_anchors = 2
|
||||
myst_heading_anchors = 3
|
||||
|
||||
# -- Custom Document processing ----------------------------------------------
|
||||
|
||||
def setup(app):
|
||||
app.add_css_file("theme_overrides.css")
|
||||
|
266
docs/features.md
266
docs/features.md
@ -1,58 +1,260 @@
|
||||
# Features
|
||||
|
||||
You can watch demos for some of these features [below](#demos).
|
||||
This table gives a summary of the features that HLS supports.
|
||||
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).
|
||||
|
||||
- Warning and error diagnostics from GHC
|
||||
- Type information and documentation on hover, [including your own comments](./configuration.md#how-to-show-local-documentation-on-hover).
|
||||
- Jump to definition: [for now only for local code definitions](https://github.com/haskell/haskell-language-server/issues/708)
|
||||
- Document symbols
|
||||
- Highlight references in document
|
||||
- Code completion
|
||||
- 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)
|
||||
- [Code evaluation](#code-evaluation), see its [Tutorial](https://github.com/haskell/haskell-language-server/blob/master/plugins/hls-eval-plugin/README.md)
|
||||
- [Integration with](#retrie-integration) [retrie](https://hackage.haskell.org/package/retrie), a powerful, easy-to-use codemodding tool
|
||||
- [Code lenses for explicit import lists](#explicit-import-lists)
|
||||
- [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)
|
||||
- [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)
|
||||
- [Module name suggestions](#module-names) for insertion or correction
|
||||
- [Call hierarchy support](#call-hierarchy)
|
||||
- [Qualify names from an import declaration](#qualify-imported-names) in your code
|
||||
- [Suggest alternate numeric formats](#alternate-number-formatting)
|
||||
| Feature | [LSP method](./what-is-hls.md#lsp-terminology) |
|
||||
|-----------------------------------------------------|---------------------------------------------------------------------------------------------------|
|
||||
| [Diagnostics](#diagnostics) | `textDocument/publishDiagnostics` |
|
||||
| [Hovers](#hovers) | `textDocument/hover` |
|
||||
| [Jump to definition](#jump-to-definition) | `textDocument/definition` |
|
||||
| [Jump to type definition](#jump-to-type-definition) | `textDocument/typeDefinition` |
|
||||
| [Find references](#find-references) | `textDocument/references` |
|
||||
| [Completions](#completions) | `textDocument/completion` |
|
||||
| [Formatting](#formatting) | `textDocument/formatting`, `textDocument/rangeFormatting` |
|
||||
| [Document symbols](#document-symbols) | `textDocument/documentSymbol` |
|
||||
| [Workspace symbols](#workspace-symbols) | `workspace/symbol` |
|
||||
| [Call hierarchy](#call-hierarchy) | `textDocument/prepareCallHierarchy`, `callHierarchy/incomingCalls`, `callHierarchy/outgoingCalls` |
|
||||
| [Highlight references](#highlight-references) | `textDocument/documentHighlight` |
|
||||
| [Code actions](#code-actions) | `textDocument/codeAction` |
|
||||
| [Code lenses](#code-lenses) | `textDocument/codeLens` |
|
||||
|
||||
## Demos
|
||||
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!
|
||||
Additionally, not all plugins are supported on all versions of GHC, see the [GHC version support page](supported-versions.md) for details.
|
||||
|
||||
### Code evaluation
|
||||
## Diagnostics
|
||||
|
||||
![Eval Demo](https://raw.githubusercontent.com/haskell/haskell-language-server/master/plugins/hls-eval-plugin/demo.gif)
|
||||
### GHC compiler errors and warnings
|
||||
Provided by: `ghcide`
|
||||
|
||||
### Retrie integration
|
||||
Provides errors and warnings from GHC as diagnostics.
|
||||
|
||||
![Retrie Demo](https://i.imgur.com/Ev7B87k.gif)
|
||||
### Hlint hints
|
||||
Provided by: `hls-hlint-plugin`
|
||||
|
||||
### Explicit import lists
|
||||
Provides hlint hints as diagnostics.
|
||||
|
||||
![Imports code lens Demo](https://imgur.com/pX9kvY4.gif)
|
||||
## Hovers
|
||||
Provided by: `ghcide`
|
||||
|
||||
### Wingman
|
||||
Type information and documentation on hover, [including from local definitions](./configuration.md#how-to-show-local-documentation-on-hover).
|
||||
|
||||
![Wingman Demo](https://user-images.githubusercontent.com/307223/92657198-3d4be400-f2a9-11ea-8ad3-f541c8eea891.gif)
|
||||
## Jump to definition
|
||||
Provided by: `ghcide`
|
||||
|
||||
### Hlint
|
||||
Jump to the definition of a name.
|
||||
|
||||
![Hlint Demo](https://user-images.githubusercontent.com/54035/110860028-8f9fa900-82bc-11eb-9fe5-6483d8bb95e6.gif)
|
||||
Known limitations:
|
||||
- Only works for [local definitions](https://github.com/haskell/haskell-language-server/issues/708).
|
||||
|
||||
### Module names
|
||||
## Jump to type definition
|
||||
Provided by: `ghcide`
|
||||
|
||||
![Module Name Demo](https://user-images.githubusercontent.com/54035/110860755-78ad8680-82bd-11eb-9845-9ea4b1cc1f76.gif)
|
||||
Known limitations:
|
||||
- Only works for [local definitions](https://github.com/haskell/haskell-language-server/issues/708).
|
||||
|
||||
### Call hierarchy
|
||||
## Find references
|
||||
Provided by: `ghcide`
|
||||
|
||||
Find references to a name within the project.
|
||||
|
||||
## Completions
|
||||
|
||||
### Code completions
|
||||
Provided by: `ghcide`
|
||||
|
||||
- Completion of names from qualified imports.
|
||||
- Completion of names from non-imported modules.
|
||||
|
||||
### Pragma completions
|
||||
Provided by: `hls-pragmas-plugin`
|
||||
|
||||
Completions for language pragmas.
|
||||
|
||||
## Formatting
|
||||
Format your code with various Haskell code formatters.
|
||||
|
||||
| Formatter | Provided by |
|
||||
|-----------------|------------------------------|
|
||||
| Brittany | `hls-brittany-plugin` |
|
||||
| Floskell | `hls-floskell-plugin` |
|
||||
| Fourmolu | `hls-fourmolu-plugin` |
|
||||
| Ormolu | `hls-ormolu-plugin` |
|
||||
| Stylish Haskell | `hls-stylish-haskell-plugin` |
|
||||
|
||||
## Document symbols
|
||||
Provided by: `ghcide`
|
||||
|
||||
Provides listing of the symbols defined in a module, used to power outline displays.
|
||||
|
||||
## Workspace symbols
|
||||
Provided by: `ghcide`
|
||||
|
||||
Provides listing of the symbols defined in the project, used to power searches.
|
||||
|
||||
## Call hierarchy
|
||||
Provided by: `hls-call-hierarchy-plugin`
|
||||
|
||||
Shows ingoing and outgoing calls for a function.
|
||||
|
||||
![Call Hierarchy in VSCode](https://github.com/haskell/haskell-language-server/raw/2857eeece0398e1cd4b2ffb6069b05c4d2308b39/plugins/hls-call-hierarchy-plugin/call-hierarchy-in-vscode.gif)
|
||||
|
||||
## Highlight references
|
||||
Provided by: `ghcide`
|
||||
|
||||
Highlights references to a name in a document.
|
||||
|
||||
## Code actions
|
||||
|
||||
### Insert missing pragmas
|
||||
Provided by: `hls-pragma-plugin`
|
||||
|
||||
Code action kind: `quickfix`
|
||||
|
||||
Inserts missing pragmas needed by GHC.
|
||||
|
||||
### Apply Hlint fixes
|
||||
Provided by: `hls-hlint-plugin`
|
||||
|
||||
Code action kind: `quickfix`
|
||||
|
||||
Applies hints, either individually or for the whole file.
|
||||
Uses [apply-refact](https://github.com/mpickering/apply-refact).
|
||||
|
||||
![Hlint Demo](https://user-images.githubusercontent.com/54035/110860028-8f9fa900-82bc-11eb-9fe5-6483d8bb95e6.gif)
|
||||
|
||||
Known limitations:
|
||||
- May have strange behaviour in files with CPP, since `apply-refact` does not support CPP.
|
||||
|
||||
### Make import lists fully explicit
|
||||
Provided by: `hls-explicit-imports-plugin`
|
||||
|
||||
Code action kind: `quickfix.literals.style`
|
||||
|
||||
Make import lists fully explicit (same as the code lens).
|
||||
|
||||
### Qualify imported names
|
||||
Provided by: `hls-qualify-imported-names-plugin`
|
||||
|
||||
Code action kind: `quickfix`
|
||||
|
||||
Rewrites imported names to be qualified.
|
||||
|
||||
![Qualify Imported Names Demo](../plugins/hls-qualify-imported-names-plugin/qualify-imported-names-demo.gif)
|
||||
|
||||
For usage see the ![readme](../plugins/hls-qualify-imported-names-plugin/README.md).
|
||||
|
||||
### Alternate Number Formatting
|
||||
### Refine import
|
||||
Provided by: `hls-refine-imports-plugin`
|
||||
|
||||
Code action kind: `quickfix.import.refine`
|
||||
|
||||
Refines imports to more specific modules when names are re-exported (same as the code lens).
|
||||
|
||||
### Add missing class methods
|
||||
Provided by: `hls-class-plugin`
|
||||
|
||||
Code action kind: `quickfix`
|
||||
|
||||
Adds placeholders for missing class methods in a class instance definition.
|
||||
|
||||
### Unfold definition
|
||||
Provided by: `hls-retrie-plugin`
|
||||
|
||||
Code action kind: `refactor.extract`
|
||||
|
||||
Extracts a definition from the code.
|
||||
|
||||
### Fold definition
|
||||
Provided by: `hls-retrie-plugin`
|
||||
|
||||
Code action kind: `refactor.inline`
|
||||
|
||||
Inlines a definition from the code.
|
||||
|
||||
![Retrie Demo](https://i.imgur.com/Ev7B87k.gif)
|
||||
|
||||
### Insert contents of Template Haskell splice
|
||||
Provided by: `hls-splice-plugin`
|
||||
|
||||
Code action kind: `refactor.rewrite`
|
||||
|
||||
Evaluates a Template Haskell splice and inserts the resulting code in its place.
|
||||
|
||||
### Convert numbers to alternative formats
|
||||
Provided by: `hls-alternate-number-format-plugin`
|
||||
|
||||
Code action kind: `quickfix.literals.style`
|
||||
|
||||
Converts numeric literals to different formats.
|
||||
|
||||
![Alternate Number Format Demo](../plugins/hls-alternate-number-format-plugin/HLSAll.gif)
|
||||
|
||||
### Add Haddock comments
|
||||
Provided by: `hls-haddock-comments-plugin`
|
||||
|
||||
Code action kind: `quickfix`
|
||||
|
||||
Adds Haddock comments for function arguments.
|
||||
|
||||
### Wingman
|
||||
Status: Not supported on GHC 9.2
|
||||
|
||||
Provided by: `hls-tactics-plugin`
|
||||
|
||||
Provides a variety of code actions for interactive code development, see https://haskellwingman.dev/ for more details.
|
||||
|
||||
![Wingman Demo](https://user-images.githubusercontent.com/307223/92657198-3d4be400-f2a9-11ea-8ad3-f541c8eea891.gif)
|
||||
|
||||
## Code lenses
|
||||
|
||||
### Add type signature
|
||||
Provided by: `ghcide`
|
||||
|
||||
Shows the type signature for bindings without type signatures, and adds it with a click.
|
||||
|
||||
### Evaluation code snippets in comments
|
||||
Provided by: `hls-eval-plugin`
|
||||
|
||||
Evaluates code blocks in comments with a click. [Tutorial](https://github.com/haskell/haskell-language-server/blob/master/plugins/hls-eval-plugin/README.md).
|
||||
|
||||
![Eval Demo](https://raw.githubusercontent.com/haskell/haskell-language-server/master/plugins/hls-eval-plugin/demo.gif)
|
||||
|
||||
### Make import lists fully explicit
|
||||
Provided by: `hls-explicit-imports-plugin`
|
||||
|
||||
Shows fully explicit import lists and rewrites them with a click (same as the code action).
|
||||
|
||||
![Imports code lens Demo](https://imgur.com/pX9kvY4.gif)
|
||||
|
||||
### Refine import
|
||||
Provided by: `hls-refine-imports-plugin`
|
||||
|
||||
Shows refined imports and applies them with a click (same as the code action).
|
||||
|
||||
### Fix module names
|
||||
Provided by: `hls-module-name-plugin`
|
||||
|
||||
Shows module name matching file path, and applies it with a click.
|
||||
|
||||
![Module Name Demo](https://user-images.githubusercontent.com/54035/110860755-78ad8680-82bd-11eb-9845-9ea4b1cc1f76.gif)
|
||||
|
||||
## Missing features
|
||||
|
||||
The following features are supported by the LSP specification but not implemented in HLS.
|
||||
Contributions welcome!
|
||||
|
||||
| Feature | Status | [LSP method](./what-is-hls.md#lsp-terminology) |
|
||||
|------------------------|------------------------------------------------------------------------------------------|-----------------------------------------------------|
|
||||
| Signature help | Unimplemented | `textDocument/signatureHelp` |
|
||||
| Jump to declaration | Unclear if useful | `textDocument/declaration` |
|
||||
| Jump to implementation | Unclear if useful | `textDocument/implementation` |
|
||||
| Renaming | [Parital implementation](https://github.com/haskell/haskell-language-server/issues/2193) | `textDocument/rename`, `textDocument/prepareRename` |
|
||||
| Folding | Unimplemented | `textDocument/foldingRange` |
|
||||
| Selection range | Unimplemented | `textDocument/selectionRange` |
|
||||
| Semantic tokens | Unimplemented | `textDocument/semanticTokens` |
|
||||
| Linked editing | Unimplemented | `textDocument/linkedEditingRange` |
|
||||
| Document links | Unimplemented | `textDocument/documentLink` |
|
||||
| Document color | Unclear if useful | `textDocument/documentColor` |
|
||||
| Color presentation | Unclear if useful | `textDocument/colorPresentation` |
|
||||
| Monikers | Unclear if useful | `textDocument/moniker` |
|
||||
|
@ -26,6 +26,31 @@ GHC versions not in the list have never been supported by HLS, or are not planne
|
||||
|
||||
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.
|
||||
|
||||
Additionally, some plugins do not have support for some GHC versions, as shown in the following table.
|
||||
As such, the functionality provided by those plugins is not available in HLS when using a GHC version which they do not support.
|
||||
|
||||
| Plugin | Unsupported GHC versions |
|
||||
|-------------------------------------|--------------------------|
|
||||
| `hls-alternate-number-plugin` | 9.2 |
|
||||
| `hls-brittany-plugin` | 9.2 |
|
||||
| `hls-call-hierarchy-plugin` | |
|
||||
| `hls-class-plugin` | 9.2 |
|
||||
| `hls-eval-plugin` | 9.2 |
|
||||
| `hls-explicit-imports-plugin` | |
|
||||
| `hls-floskell-plugin` | |
|
||||
| `hls-fourmolu-plugin` | |
|
||||
| `hls-haddock-comments-plugin` | 9.2 |
|
||||
| `hls-hlint-plugin` | 9.2 |
|
||||
| `hls-module-name-plugin` | |
|
||||
| `hls-ormolu-plugin` | |
|
||||
| `hls-pragmas-plugin` | |
|
||||
| `hls-qualify-imported-names-plugin` | |
|
||||
| `hls-refine-imports-plugin` | |
|
||||
| `hls-retrie-plugin` | 9.2 |
|
||||
| `hls-splice-plugin` | 9.2 |
|
||||
| `hls-stylish-haskell-plugin` | 9.0, 9.2 |
|
||||
| `hls-tactics-plugin` | 9.2 |
|
||||
|
||||
### Using deprecated GHC versions
|
||||
|
||||
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).
|
||||
|
@ -33,6 +33,7 @@ Here are a few pieces of jargon that you may come across in the HLS docs or when
|
||||
- *Completion item*: An item that can be inserted into the text, including its metadata.
|
||||
- *Diagnostic*: Any information about the project that is shown in the editor, including errors, warnings, and hints from tools such as hlint.
|
||||
- *Semantic highlighting*: Special syntax highlighting performed by the server.
|
||||
- *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.
|
||||
|
||||
## haskell-language-server
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user