Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rework features documentation #2603

Merged
merged 15 commits into from
Jan 21, 2022
Merged

Rework features documentation #2603

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
73eef27
Rework features documentation
michaelpj Jan 19, 2022
05bc777
Add a couple of known limitations
michaelpj Jan 19, 2022
1614a9f
Move plugin GHC version support to other page
michaelpj Jan 19, 2022
b048784
Purge useless status column
michaelpj Jan 19, 2022
5797eb9
Update docs/features.md
eddiemundo Jan 19, 2022
49db369
Update docs/features.md
eddiemundo Jan 19, 2022
42527ba
Update docs/features.md
eddiemundo Jan 19, 2022
ff4f00a
Update docs/features.md
eddiemundo Jan 19, 2022
10abe6c
Update docs/features.md
eddiemundo Jan 19, 2022
46d4c71
Update docs/features.md
eddiemundo Jan 19, 2022
9161140
Merge branch 'master' into mpj/features-doc
michaelpj Jan 20, 2022
002a96c
Merge branch 'master' into mpj/features-doc
pepeiborra Jan 20, 2022
0171d34
Clarify text
michaelpj Jan 21, 2022
28369f7
Mention limitations of apply-refact
michaelpj Jan 21, 2022
c51c26f
Merge branch 'master' into mpj/features-doc
mergify[bot] Jan 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/_static/theme_overrides.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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;
}
}
7 changes: 6 additions & 1 deletion docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,4 +86,9 @@

# 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")
269 changes: 234 additions & 35 deletions docs/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,58 +1,257 @@
# Features

You can watch demos for some of these features [below](#demos).

- 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)

## Demos

### Code evaluation
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).

![Eval Demo](https://raw.githubusercontent.com/haskell/haskell-language-server/master/plugins/hls-eval-plugin/demo.gif)
| 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` |

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

![Retrie Demo](https://i.imgur.com/Ev7B87k.gif)
## Diagnostics

### Explicit import lists
### GHC compiler errors and warnings
Provided by: `ghcide`

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

### Wingman
### Hlint hints
Provided by: `hls-hlint-plugin`

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

### Hlint
## Hovers
Provided by: `ghcide`

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

### Module names
## Jump to definition
Provided by: `ghcide`

![Module Name Demo](https://user-images.githubusercontent.com/54035/110860755-78ad8680-82bd-11eb-9845-9ea4b1cc1f76.gif)
Jump to the definition of a name.

Known limitations:
- Only works for [local definitions](https://github.com/haskell/haskell-language-server/issues/708).

## Jump to type definition
Provided by: `ghcide`

Known limitations:
- Only works for [local definitions](https://github.com/haskell/haskell-language-server/issues/708).

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

### Call hierarchy
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
Anton-Latukha marked this conversation as resolved.
Show resolved Hide resolved
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)

### 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).
eddiemundo marked this conversation as resolved.
Show resolved Hide resolved

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

### Alternate Number Formatting
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` |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does it worth mention the wip pr #2565?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Eh, I'd wait until it's merged. It might never be, who knows!

| 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` |
24 changes: 24 additions & 0 deletions docs/supported-versions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,30 @@ 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 are not supported on some GHC versions, as shown in the following table.

| Plugin | Unsupported versions |
Copy link
Collaborator

@Anton-Latukha Anton-Latukha Jan 20, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mention that it is GHC versions.

Also stating in HLS docs in article "Supported versions" that some plugins correspond to some Unsupported GHC versions - it raises a question, is HLS not supporting them for these GHCs?

"Additionally, some plugins are not supported on some GHC versions, as shown in the following table." only magnifies that belief: plugins are really are unsupported by HLS for particular versions. When the implication is in a different direction. It is plugins that do not support new GHCs & HLS releases that support those GHCs.

Stating: "Bounds on the support of GHC releases" & declaring the bounds below as Cabal bounds - would align the knowledge & understanding.

The first culprit of a particular plugin - is that it needs to support new GHC, which means support HLS API for that release, which means person goes - looks at .cabal description of the plugin in the mainline branch, clones & tweaks the boundary & observes the result & starts from there, & goes lurking on according reports/PRs.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm sorry, I'm not sure I quite understand what you're saying. I will try and make the text clearer so that it's obvious that the lack of support is because the plugin lacks support for that version of GHC.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep.

Despite using English, sometimes I still do basic errors, like making a question while sequencing the words as a statement.

There is still a structural question, between HLS-plugin & GHC, there is a major structural part - HLS, but the table directs to compatibility with GHC. But that does not matter, users/contributors would raise the question if they would need it.

|-------------------------------------|---------------------------------|
| `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).
Expand Down
1 change: 1 addition & 0 deletions docs/what-is-hls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down