Rework features documentation #2603

michaelpj · 2022-01-19T14:11:34Z

REMINDER: RTD provides a preview of the rendered documentation via a PR status.

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.

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.

michaelpj · 2022-01-19T14:15:42Z

Also I would like to encourage plugin authors to provide slightly more substantial feature descriptions than my one-sentence summaries 😅

michaelpj · 2022-01-19T14:19:34Z

Possible changes I thought about:

GHC version compatibility in a table on the GHC support page instead?
Code action kinds for each code action in a table somewhere instead of spread out?

jneira · 2022-01-19T14:32:46Z

awesome stuff, many many thanks
someone in the vscode extension asked recently for info like this (also key bindings but that is totally editor specific)
haskell/vscode-haskell#525

michaelpj · 2022-01-19T14:33:40Z

Hmm, so maybe it would help to call out that you may need to consult your client to find out how to actually trigger these features?

jneira · 2022-01-19T14:37:17Z

there is an issue in this repo asking for an improvement of the section changed here: #2327
not sure if the pr fullfills some of the suggestions done there (or if it could do it)

michaelpj · 2022-01-19T14:39:28Z

I'm not convinced by the editor table, I think users should just consult the documentation for the editor, but otherwise I think this gets us a lot closer. Known limitations would be great... I just don't know the limitations in most cases. I think we'd need some help from plugin authors to make this significantly better.

jneira

great work as usual, I like the actual version but the alternatives sounds good as well

michaelpj · 2022-01-19T16:59:09Z

Ah yeah, my concern with the GHC version support stuff being spread out is that it's harder to maintain. Which is maybe the killer argument. This information is no good if it's out-of-date, and the GHC version support page is naturally the place we're going to think to update when we do GHC version support stuff. So for that reason I think it should go there, maybe with a link from here.

GuillaumeDesforges · 2022-01-19T17:00:45Z

Looks nice!

I've tried using Ctrl+F on some simple things I'd look for, like "hlint" or "explicit", and I got the info right away 👍
I especially like the "missing features" part, which helps quickly figuring out why something can't be done (e.g. renaming).

jneira · 2022-01-19T17:59:21Z

docs/features.md

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


does it worth mention the wip pr #2565?

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

michaelpj · 2022-01-19T19:15:06Z

Moved plugin version support table to GHC support page
Added a few known limitations
Removed fairly pointless "Status" column from main feature table

Anton-Latukha · 2022-01-19T19:29:24Z

Personally, I think that in HLS docs it is sound to have 1) plugin API info 2) examples on how to develop them. Maybe, maaybe, include core plugins & their info & from time to time - statuses.

And lists of plugins, their description & status updates seem like should be in a separate repo. A repo that becomes a wiki-(catalog of interlinks)-(knowledge db) on existing plugins & what they support.
That would allow to not get notifications & to not review the plugin list status update PRs.

Also woul'd be good if plugins could themselves tell what they support, through Cabal descriptions or whatever. Or for HLS to be able to report that plugin is discarded because it has no support for new releases.

That again goes to the coupling, if plugins are bundles - to tell is it supported or not - the closest people who have current updates on that info become core team responcibility.

What do you think on this?

michaelpj · 2022-01-19T20:07:53Z

plugin API info 2) examples on how to develop them

I don't think either of those are appropriate for a features page aimed at users of HLS, though?

As for the rest... the point of this PR is just to make the features page better, not redo the entire way that plugins are organized and documented!

eddiemundo · 2022-01-19T20:09:47Z

Some of the plugins have more substantial READMEs, should we inline some or most of that information here?

michaelpj · 2022-01-19T20:28:02Z

Some of the plugins have more substantial READMEs, should we inline some or most of that information here?

Maybe. Probably some! I think we should keep this page relatively lightweight, and maybe if there are plugins that have lots to say (e.g. I'm sure there is lots to say about Wingman), we could add a documentation page specifically for them.

eddiemundo · 2022-01-19T20:30:53Z

Ah OK I'm thinking now we could just link to the readmes from this page if they have any.

After seeing #2603 might as well improve the docs a little so we can maybe link to it.

Add link to qualify imported names readme

docs/features.md

i don't know how to use github

malteneuss · 2022-01-19T22:05:29Z

someone in the vscode extension asked recently for info like this (also key bindings but that is totally editor specific)
haskell/vscode-haskell#525

Regarding documentation of key-bindings in HLS clients/editors, which is important for end-users, i'd like to propose the following idea as some future improvement to minimize, repeated manual work:

Could we mold the feature information into structured data, and then generate this page/table based on that?
Basically, provide (LSP Protocoll functions <-> Descriptions, Status, other Info). Then a client like vscode can provide (keybindings in vscode <-> LSP Protocoll functions), and combine both to generate a (keybindings in vscode <-> Descriptions, Status, other Info) Table on their documentation page.

That could be repeated for every HLS client in other editors.

After seeing #2603 might as well improve the docs a little so we can maybe link to it. Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

GuillaumeDesforges · 2022-01-20T07:35:16Z

Would it be possible to add a link to each plugin's homepage, so that users can go learn more about them?

michaelpj · 2022-01-20T11:19:45Z

Would it be possible to add a link to each plugin's homepage, so that users can go learn more about them?

@eddiemundo has been doing that, which is great. At the moment the existence of these is a bit spotty. I'd like to make them a more "proper" part of the documentation build, but that can happen later.

Could we mold the feature information into structured data, and then generate this page/table based on that?
Basically, provide (LSP Protocoll functions <-> Descriptions, Status, other Info). Then a client like vscode can provide (keybindings in vscode <-> LSP Protocoll functions), and combine both to generate a (keybindings in vscode <-> Descriptions, Status, other Info) Table on their documentation page.

I guess my feeling is that the point of the LSP is that you get to do #clients + #servers work rather than #clients*#servers, and so I kind of want the same for docs: let the user put the server doc and the client doc together and do the "join" themselves. But then that is less user friendly.

Also we can't give keybindings for emacs in general since they're mapped to all sorts of things by various emacs distributions!

Anyway, a few additional requests in this thread, I'll make some issues for them so they don't get lost.

michaelpj · 2022-01-20T11:23:49Z

Better plugin doc: #2066
Keybindings: #2613

Anton-Latukha · 2022-01-20T13:44:53Z

docs/supported-versions.md

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


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.

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.

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.

Anton-Latukha · 2022-01-20T13:47:21Z

#2603 (comment) well, sometimes a typo changes the reading.

The main point there - is that, as I think of it, plugins better to not be included into the documentation of HLS at all, only info on how to develop them & have "for additional features/to expend HLS - use plugins: ".

#2603 (comment)

As for the rest... the point of this PR is just to make the features page better, not redo the entire way that plugins are organized and documented!

Nothing is more permanent than the temporary. Starting to catalog feature-by-feature plugin abilities on Features page, means that HLS means that plugins & their features is HLS scope also, so users would grow to expect that all plugin feature information cataloged there in this form, and that in short order plugins & users would start opening PRs to add their info into this article, which means permanent maintenance of the page, until design changes.

Besides even the scope of haskell-language-server is anthropologically perceived as development, not documentation. Because of the code development scope, people tend to treat repo as a code development repository and so completely forget about documentation.

If repo has documentation to update - it is additional requirement during the cycle of work & additional mental constraint to currently have in the scope (to not forget to update that bound in docs on plugin configuration change, or on feature added).

"Features" page can be useful to state the basic functionality or the core projects of HLS & it is a great way to empirically transmit the structural knowledge/understanding. It is one thing to put in words what ghcide is in Readme, or its article & the other to empirically understand the domain of user interfacing that it does, knowing that it handles so and so - means that this code processing is present & the agenda of ghcide & so agenda (of contributor) aligns with the project and code is in there, which means - go find it there, work & improvements to it would be accepted. It is overall also important that it forms the overall understanding of what ghcide does when to look from the user, which deepens the HLS stack understanding. But when all features are mentioned & ghcide is mentioned between a lot of plugins - that prevents to empirically infer the ghcide understanding & so scope & functionality of it stay not understood by the reader.

I do not want to drawn the process in my thoughts. Just wanted to drive attention to the points that nothing is more permanent than the temporary, and that design decisions and maintenance required by that design matters.

Just giving an observation.

docs/features.md

malteneuss · 2022-01-20T15:52:44Z

I guess my feeling is that the point of the LSP is that you get to do #clients + #servers work rather than #clients*#servers, and so I kind of want the same for docs: let the user put the server doc and the client doc together and do the "join" themselves. But then that is less user friendly.

"#clients + #servers work .. for docs" is a nice summary what i had in mind. My proposal is to not let the users "join" that info (as you said as well); let the HLS clients do that (let them worry about their keybindings). But possibly we can make their join work much easier by agreeing on and providing features info as structured data, so that the join can be automated on their side.

pepeiborra · 2022-01-20T17:47:37Z

This is super-awesome, thank you @michaelpj

michaelpj · 2022-01-21T10:43:54Z

so users would grow to expect that all plugin feature information cataloged there in this form, and that in short order plugins & users would start opening PRs to add their info into this article, which means permanent maintenance of the page, until design changes.

That all sounds pretty good to me. At the moment we have basically no content about these things, so having some is a distinct improvement.

But when all features are mentioned & ghcide is mentioned between a lot of plugins - that prevents to empirically infer the ghcide understanding & so scope & functionality of it stay not understood by the reader.

I think we still have a disconnect about who the audience of this page is. I think the audience of this page is end-users, i.e. people who use HLS but don't contribute. Understanding the structure of HLS is of no use to them, but knowing that a feature is associated with ghcide might be of some use.

Explaining the structure can be usefully done as part of the contributing docs, IMO.

michaelpj · 2022-01-21T10:45:58Z

Okay, I think this is good enough state now.

michaelpj requested review from jneira and Anton-Latukha January 19, 2022 14:11

jneira approved these changes Jan 19, 2022

View reviewed changes

jneira mentioned this pull request Jan 19, 2022

Improve features list on website #2327

Closed

jneira linked an issue Jan 19, 2022 that may be closed by this pull request

Improve features list on website #2327

Closed

Add a couple of known limitations

05bc777

jneira reviewed Jan 19, 2022

View reviewed changes

michaelpj added 2 commits January 19, 2022 19:16

Move plugin GHC version support to other page

1614a9f

Purge useless status column

b048784

michaelpj force-pushed the mpj/features-doc branch from df0db5f to b048784 Compare January 19, 2022 19:17

eddiemundo added a commit that referenced this pull request Jan 19, 2022

Improve qualified import plugin readme

9bc684a

After seeing #2603 might as well improve the docs a little so we can maybe link to it.

eddiemundo mentioned this pull request Jan 19, 2022

Improve qualified import plugin readme #2605

Merged

eddiemundo added 3 commits January 19, 2022 15:53

Update docs/features.md

5797eb9

Add link to qualify imported names readme

Update docs/features.md

49db369

Update docs/features.md

42527ba

eddiemundo reviewed Jan 19, 2022

View reviewed changes

docs/features.md Outdated Show resolved Hide resolved

Update docs/features.md

ff4f00a

eddiemundo reviewed Jan 19, 2022

View reviewed changes

docs/features.md Outdated Show resolved Hide resolved

Update docs/features.md

10abe6c

eddiemundo reviewed Jan 19, 2022

View reviewed changes

docs/features.md Outdated Show resolved Hide resolved

Update docs/features.md

46d4c71

i don't know how to use github

mergify bot added a commit that referenced this pull request Jan 20, 2022

Improve qualified import plugin readme (#2605)

905f8f7

After seeing #2603 might as well improve the docs a little so we can maybe link to it. Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Merge branch 'master' into mpj/features-doc

9161140

michaelpj mentioned this pull request Jan 20, 2022

Include keybindings for common clients in documentation #2613

Closed

jneira mentioned this pull request Jan 20, 2022

Document the commands provided by the extension and corresponding key bindings haskell/vscode-haskell#525

Open

Anton-Latukha reviewed Jan 20, 2022

View reviewed changes

docs/features.md Show resolved Hide resolved

pepeiborra and others added 2 commits January 20, 2022 17:47

Merge branch 'master' into mpj/features-doc

002a96c

Clarify text

0171d34

Mention limitations of apply-refact

28369f7

michaelpj added the merge me Label to trigger pull request merge label Jan 21, 2022

Merge branch 'master' into mpj/features-doc

c51c26f

mergify bot merged commit f0bbc39 into haskell:master Jan 21, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rework features documentation #2603

Rework features documentation #2603

michaelpj commented Jan 19, 2022 •

edited by gitpod-io bot

michaelpj commented Jan 19, 2022

michaelpj commented Jan 19, 2022

jneira commented Jan 19, 2022

michaelpj commented Jan 19, 2022

jneira commented Jan 19, 2022

michaelpj commented Jan 19, 2022

jneira left a comment

michaelpj commented Jan 19, 2022

GuillaumeDesforges commented Jan 19, 2022

jneira Jan 19, 2022

michaelpj Jan 19, 2022

michaelpj commented Jan 19, 2022

Anton-Latukha commented Jan 19, 2022 •

edited

michaelpj commented Jan 19, 2022

eddiemundo commented Jan 19, 2022

michaelpj commented Jan 19, 2022

eddiemundo commented Jan 19, 2022

malteneuss commented Jan 19, 2022

GuillaumeDesforges commented Jan 20, 2022 •

edited

michaelpj commented Jan 20, 2022

michaelpj commented Jan 20, 2022

Anton-Latukha Jan 20, 2022 •

edited

michaelpj Jan 21, 2022

Anton-Latukha Jan 21, 2022

Anton-Latukha commented Jan 20, 2022 •

edited

malteneuss commented Jan 20, 2022

pepeiborra commented Jan 20, 2022

michaelpj commented Jan 21, 2022

michaelpj commented Jan 21, 2022

Rework features documentation #2603

Rework features documentation #2603

Conversation

michaelpj commented Jan 19, 2022 • edited by gitpod-io bot

michaelpj commented Jan 19, 2022

michaelpj commented Jan 19, 2022

jneira commented Jan 19, 2022

michaelpj commented Jan 19, 2022

jneira commented Jan 19, 2022

michaelpj commented Jan 19, 2022

jneira left a comment

Choose a reason for hiding this comment

michaelpj commented Jan 19, 2022

GuillaumeDesforges commented Jan 19, 2022

jneira Jan 19, 2022

Choose a reason for hiding this comment

michaelpj Jan 19, 2022

Choose a reason for hiding this comment

michaelpj commented Jan 19, 2022

Anton-Latukha commented Jan 19, 2022 • edited

michaelpj commented Jan 19, 2022

eddiemundo commented Jan 19, 2022

michaelpj commented Jan 19, 2022

eddiemundo commented Jan 19, 2022

malteneuss commented Jan 19, 2022

GuillaumeDesforges commented Jan 20, 2022 • edited

michaelpj commented Jan 20, 2022

michaelpj commented Jan 20, 2022

Anton-Latukha Jan 20, 2022 • edited

Choose a reason for hiding this comment

michaelpj Jan 21, 2022

Choose a reason for hiding this comment

Anton-Latukha Jan 21, 2022

Choose a reason for hiding this comment

Anton-Latukha commented Jan 20, 2022 • edited

malteneuss commented Jan 20, 2022

pepeiborra commented Jan 20, 2022

michaelpj commented Jan 21, 2022

michaelpj commented Jan 21, 2022

michaelpj commented Jan 19, 2022 •

edited by gitpod-io bot

Anton-Latukha commented Jan 19, 2022 •

edited

GuillaumeDesforges commented Jan 20, 2022 •

edited

Anton-Latukha Jan 20, 2022 •

edited

Anton-Latukha commented Jan 20, 2022 •

edited