Implement signature help #4626

jian-lin · 2025-06-08T21:49:42Z

Closes #3598

I will update progress here.

This PR also relates to #2348 because we let mkDocMap expose the argument doc map.

2025-06-02 - 2025-06-08

Add basic boilerplate for signature help plugin
- commit: 7a54a1d
- click for screenshot

2025-06-09 - 2025-07-13

Finish signature help plugin MVP: show function signature and highlight the current parameter
- commit: 9168b74
- click for video demo
  
  Screencast.From.2025-07-13.02-11-44.webm

2025-07-14 - 2025-07-20

Add basic tests. Some of them are not passed for now.
- commit: 62fbccf

2025-07-21 - 2025-07-27

Change expected test results considering the cursor shape (a6635ca)
Replace maybe with case for better readability (bf0b4d5)
Call extractInfoFromSmallestContainingFunctionApplicationAst once (c95d6e4)

2025-07-28 - 2025-08-03

Show more types: each type as one signature help (d603ec4)
Add tests for kind signatures and higher-order function (dca1311) (471958f)

2025-08-04 - 2025-08-10

Use structured type and type string to generate signature help (9bea0e3)
Add more tests
- middle => (fdd5acd)
- => in argument (c6ece42)
- RankNTypes(forall in middle) (fe2d618 and 081ea8f)
- LinearTypes (c3224d7)

2025-08-11 - 2025-08-17

Show function documentation in signature help (a522e88)
Show function argument documentation in signature help (d826d06)
Do not error if doc is not available (35399e7)
click for screenshots

2025-08-18 - 2025-08-24

Upstream getSignatureHelp to lsp-test: Add signature help request to lsp-test lsp#621
Make signature helps reproducible in tests (eeeb283)
Do not show uris in the argument documentation (f1d19ba)
Add tests
- imported function with argument doc (433a8ad)
- imported function with no doc (d3d7d12)
Remember previous active signature (e6702b7)
Show signature help even when there are type applications (800f908)
Fix tests for ghc > 9.8
- changed doc (cb84480)
- Any becomes ZonkAny 0 (c7931a2)
Add myself as codeowner of hls-signature-help-plugin (b6d4617)
Add hls-signature-help-plugin to some documentation files (9a1de4e)

michaelpj · 2025-06-09T07:53:42Z

hls-plugin-api/src/Ide/Types.hs

@@ -764,6 +770,10 @@ instance PluginRequestMethod Method_TextDocumentDocumentSymbol where
            si = SymbolInformation name' (ds ^. L.kind) Nothing parent (ds ^. L.deprecated) loc
        in [si] <> children'

+-- TODO(@linj) is this correct?


I think this is reasonable. Really combineResponses should have a way to return an error. There are a bunch of methods where it really only makes sense if we have one handler.

We could try to combine responses: we would combine the signatures, and so long as only one of them indicated an active signature it would be okay. But that's a bit sketchy and I doubt we'll have several anyway!

TODO: - handle more cases - add successful and (currently failed) tests - show documentation

michaelpj

I think really worth trying to start getting some tests in place!

plugins/hls-signature-help-plugin/src/Ide/Plugin/SignatureHelp.hs

@fendor

This is discussed with @fendor.

This improves performance. It also improves correctness because functionName, functionType and argumentNumber are extracted from the same AST.

Vscode and Emacs(eglot) seems to treat newline as a normal char.

See comment for a comparison with alternative methods.

jian-lin · 2025-08-07T09:26:21Z

All tests on Linux and darwin passed! Not sure what happens on windows.

Added a few more tests and now 3 out of 87 tests failed.

Test 5 does not pass.

plugins/hls-signature-help-plugin/src/Ide/Plugin/SignatureHelp.hs

jian-lin · 2025-08-07T18:34:02Z

plugins/hls-signature-help-plugin/src/Ide/Plugin/SignatureHelp.hs

+findArgumentRanges :: Type -> [(UInt, UInt)]
+findArgumentRanges functionType =
+    let functionTypeString = printOutputableOneLine functionType
+        functionTypeStringLength = fromIntegral $ T.length functionTypeString
+        splitFunctionTypes = filter notTypeConstraint $ splitFunTysIgnoringForAll functionType
+        splitFunctionTypeStrings = printOutputableOneLine . fst <$> splitFunctionTypes
+        -- reverse to avoid matching "a" of "forall a" in "forall a. a -> a"
+        reversedRanges =
+            drop 1 $ -- do not need the range of the result (last) type
+                findArgumentStringRanges
+                    0
+                    (T.reverse functionTypeString)
+                    (T.reverse <$> reverse splitFunctionTypeStrings)
+     in reverse $ modifyRange functionTypeStringLength <$> reversedRanges
+    where
+        modifyRange functionTypeStringLength (start, end) =
+            (functionTypeStringLength - end, functionTypeStringLength - start)
+
+{-
+The implemented method uses both structured type and unstructured type string.
+It provides good enough results and is easier to implement than alternative
+method 1 or 2.
+
+Alternative method 1: use only structured type
+This method is hard to implement because we need to duplicate some logic of 'ppr' for 'Type'.
+Some tricky cases are as follows:
+- 'Eq a => Num b -> c' is shown as '(Eq a, Numb) => c'
+- 'forall' can appear anywhere in a type when RankNTypes is enabled
+  f :: forall a. Maybe a -> forall b. (a, b) -> b
+- '=>' can appear anywhere in a type
+  g :: forall a b. Eq a => a -> Num b => b -> b
+- ppr the first argument type of '(a -> b) -> a -> b' is 'a -> b' (no parentheses)
+- 'forall' is not always shown
+
+Alternative method 2: use only unstructured type string
+This method is hard to implement because we need to parse the type string.
+Some tricky cases are as follows:
+- h :: forall a (m :: Type -> Type). Monad m => a -> m a
+-}
+findArgumentStringRanges :: UInt -> Text -> [Text] -> [(UInt, UInt)]


Context:

Implement signature help #4626 (comment)

Implement signature help #4626 (comment)

Implement signature help #4626 (comment)

@michaelpj

I implemented a mixed way which uses both structured type and type string. See the comment for the reason of doing it this way instead of using only structured type or only type string.

It seems to work pretty well. "3 out of 87 tests failed".

One failed test case is f :: Integer -> Num Integer => Integer -> Integer. We matched Num Integer as the first argument. This probably can be fixed by using regex.

Another similar failed test case is f :: forall l. l -> forall a. a -> a. When we should highlight the argument l, we highlight the l for the second forall.

Here is another failed test case.

f :: a -> forall a. a -> a f = _

The printed type string for f is f :: forall a. a -> forall a1. a1 -> a1. This seems tricky to fix in the current implementation because it needs us to duplicate the renaming logic (the second forall a becomes forall a1) of ppr.

This case only happens when RankNTypes is used so I do not think it is very common.

I'm wondering how bad it would be to just use the structured type and re-implement some pretty-printing logic. I think the only bit we'd need to duplicate would be the printing of ->, =>, and forall? Maybe that's okay?

plugins/hls-signature-help-plugin/src/Ide/Plugin/SignatureHelp.hs

michaelpj · 2025-08-10T15:44:33Z

Another thing we should think about: type arguments.

id :: forall a . a -> a
id x = x

id @...
      ^^ --- we probably want to consider the "a" a parameter so we can highlight it here when the user is providing a type

-- with RequiredTypeArguments
id :: forall a -> a -> a
id _ x = x

id 
    ^^ -- here again we need to highlight the forall

Type arguments are kind of annoying because they might be optional (with normal foralls), or they might be required (with required type arguments).

plugins/hls-signature-help-plugin/test/Main.hs

jian-lin · 2025-08-16T09:53:16Z

ghcide/src/Development/IDE/Spans/Common.hs

 type DocMap = NameEnv SpanDoc
 type TyThingMap = NameEnv TyThing
+type ArgDocMap = NameEnv (IntMap SpanDoc)


Instead of creating a new ArgDocMap, an alternative implementation is to extend DocMap to NameEnv (SpanDoc, IntMap SpanDoc).

That sounds sensible to me? Any reason not to do that?

I do not have a strong opinion on this. I will change the code to type DocMap = NameEnv (SpanDoc, IntMap SpanDoc).

Looking at the code it seems like it would simplifiy things quite a lot.

Now I have second thoughts about this because the alternative implementation type DocMap = NameEnv (SpanDoc, IntMap SpanDoc) is semantically incorrect. The semantically correct version should be type DocMap = NameEnv (Maybe SpanDoc, IntMap SpanDoc) or type DocMap = NameEnv (Maybe SpanDoc, Maybe (IntMap SpanDoc)) because a Name can have only function doc or arg doc.

I prefer to keep the old implementation, i.e., introducing a new ArgDocMap, since the semantically correct version of the alternative implementation seems more complicated.

This makes tests less flaky.

Uris are already shown in the function documentation. No need to show them in the argument documentation again.

jian-lin · 2025-08-22T02:40:15Z

plugins/hls-signature-help-plugin/test/Main.hs

I am a bit confused about this failed test in CI which I cannot reproduce locally.

In CI, the function doc of pure is "\n\nLift a value.\n\n". Locally, it is "\n\nLift a value.\n\n\\[Documentation\\]\\(file://.*\\)\n\n\\[Source\\]\\(file://.*\\)\n\n". So somehow in CI HLS fails to find uris of the imported function pure.

type constraint with kind signatures type constraint with kind signatures 2: FAIL (0.15s) src/Test/Hls.hs:400: Full Line: "x = pure True" Cursor Column: " ^" Prefix Text: "" expected: Just (SignatureHelp {_signatures = [SignatureInformation {_label = "pure :: forall (f :: Type -> Type) a. Applicative f => a -> f a", _documentation = Just (InR (MarkupContent {_kind = MarkupKind_Markdown, _value = "\n\nLift a value.\n\n\\[Documentation\\]\\(file://.*\\)\n\n\\[Source\\]\\(file://.*\\)\n\n"})), _parameters = Just [ParameterInformation {_label = InR (55,56), _documentation = Nothing}], _activeParameter = Just (InL 0)},SignatureInformation {_label = "pure :: Bool -> IO Bool", _documentation = Just (InR (MarkupContent {_kind = MarkupKind_Markdown, _value = "\n\nLift a value.\n\n\\[Documentation\\]\\(file://.*\\)\n\n\\[Source\\]\\(file://.*\\)\n\n"})), _parameters = Just [ParameterInformation {_label = InR (8,12), _documentation = Nothing}], _activeParameter = Just (InL 0)},SignatureInformation {_label = "pure :: forall a. a -> IO a", _documentation = Just (InR (MarkupContent {_kind = MarkupKind_Markdown, _value = "\n\nLift a value.\n\n\\[Documentation\\]\\(file://.*\\)\n\n\\[Source\\]\\(file://.*\\)\n\n"})), _parameters = Just [ParameterInformation {_label = InR (18,19), _documentation = Nothing}], _activeParameter = Just (InL 0)}], _activeSignature = Just 0, _activeParameter = Just (InL 0)}) but got: Just (SignatureHelp {_signatures = [SignatureInformation {_label = "pure :: forall (f :: Type -> Type) a. Applicative f => a -> f a", _documentation = Just (InR (MarkupContent {_kind = MarkupKind_Markdown, _value = "\n\nLift a value.\n\n"})), _parameters = Just [ParameterInformation {_label = InR (55,56), _documentation = Nothing}], _activeParameter = Just (InL 0)},SignatureInformation {_label = "pure :: Bool -> IO Bool", _documentation = Just (InR (MarkupContent {_kind = MarkupKind_Markdown, _value = "\n\nLift a value.\n\n"})), _parameters = Just [ParameterInformation {_label = InR (8,12), _documentation = Nothing}], _activeParameter = Just (InL 0)},SignatureInformation {_label = "pure :: forall a. a -> IO a", _documentation = Just (InR (MarkupContent {_kind = MarkupKind_Markdown, _value = "\n\nLift a value.\n\n"})), _parameters = Just [ParameterInformation {_label = InR (18,19), _documentation = Nothing}], _activeParameter = Just (InL 0)}], _activeSignature = Just 0, _activeParameter = Just (InL 0)}) Use -p '/type constraint with kind signatures 2/' to rerun this test only.

WIP: add basic boilerplate for signature help plugin

7a54a1d

michaelpj reviewed Jun 9, 2025

View reviewed changes

WIP: finish signature help plugin MVP

9168b74

TODO: - handle more cases - add successful and (currently failed) tests - show documentation

jian-lin force-pushed the pr/signature-help branch from 7a02359 to 9168b74 Compare July 12, 2025 18:33

michaelpj reviewed Jul 13, 2025

View reviewed changes

jian-lin added 3 commits July 16, 2025 13:51

WIP: remove unused dependencies

4d7fa57

WIP: fix func-tests

622c8ec

WIP: add basic tests

62fbccf

jian-lin force-pushed the pr/signature-help branch from 67f5cdb to 62fbccf Compare July 16, 2025 06:52

jian-lin added 9 commits July 25, 2025 15:45

Change expected test results considering the cursor shape

a6635ca

This is discussed with @fendor.

Replace maybe with case for better readability

bf0b4d5

Call extractInfoFromSmallestContainingFunctionApplicationAst once

c95d6e4

This improves performance. It also improves correctness because functionName, functionType and argumentNumber are extracted from the same AST.

Add missing ParameterInformation for multi-line tests

3dc1ec8

Vscode and Emacs(eglot) seems to treat newline as a normal char.

Add a signature help test for type constraint with kind signatures

dca1311

Add a signature help test for higher-order function

471958f

Show more types: each type as one signature help

d603ec4

Adjust import for the removal of hie-compat (haskell#4613)

faa4e48

Use structured type and type string to generate signature help

9bea0e3

See comment for a comparison with alternative methods.

jian-lin added 5 commits August 8, 2025 02:17

Add signature help test: 2 type constraints

db5e59e

Add signature help test: middle =>

fdd5acd

Test 5 does not pass.

Add signature help test: => in argument

c6ece42

Add 2 signature help tests: RankNTypes(forall in middle)

fe2d618

Add signature help test: LinearTypes

c3224d7

jian-lin commented Aug 7, 2025

View reviewed changes

Add another signature help tests: RankNTypes(forall in middle)

081ea8f

jian-lin added 2 commits August 15, 2025 15:50

Show function documentation in signature help

a522e88

Show function argument documentation in signature help

d826d06

jian-lin commented Aug 15, 2025

View reviewed changes

plugins/hls-signature-help-plugin/test/Main.hs Show resolved Hide resolved

jian-lin added 3 commits August 16, 2025 09:33

Rename a local variable

62f2e41

Do not error if doc is not available

35399e7

Add a helper function to create markdown doc

c0f7844

jian-lin commented Aug 16, 2025

View reviewed changes

This was referenced Aug 18, 2025

Add "Go to type" hyperlinks in the hover popup (like Rust has) #4691

Open

Add signature help request to lsp-test haskell/lsp#621

Open

jian-lin added 12 commits August 22, 2025 09:36

Make signature helps reproducible before comparing them

eeeb283

This makes tests less flaky.

Do not show uris in the argument documentation

f1d19ba

Uris are already shown in the function documentation. No need to show them in the argument documentation again.

Add a signature help test: imported function with argument doc

433a8ad

Add a signature help test: imported function with no doc

d3d7d12

Remove an outdated TODO item

e0a7e8b

Remember previous active signature

e6702b7

Update a TODO item

3d7a67b

Show signature help even when there are type applications

800f908

Fix some tests for ghc > 9.8 due to changed doc

cb84480

Fix some tests for ghc > 9.8 due to changed type: Any -> ZonkAny 0

c7931a2

Add jian-lin as codeowner of hls-signature-help-plugin

b6d4617

Add hls-signature-help-plugin to some documentation files

9a1de4e

jian-lin commented Aug 22, 2025

View reviewed changes

Uh oh!

Implement signature help #4626

Are you sure you want to change the base?

Implement signature help #4626

Uh oh!

Conversation

jian-lin commented Jun 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

2025-06-02 - 2025-06-08

2025-06-09 - 2025-07-13

2025-07-14 - 2025-07-20

2025-07-21 - 2025-07-27

2025-07-28 - 2025-08-03

2025-08-04 - 2025-08-10

2025-08-11 - 2025-08-17

2025-08-18 - 2025-08-24

Uh oh!

michaelpj Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

michaelpj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jian-lin commented Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jian-lin Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michaelpj Aug 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

michaelpj commented Aug 10, 2025

Uh oh!

Uh oh!

jian-lin Aug 16, 2025

Choose a reason for hiding this comment

Uh oh!

michaelpj Aug 17, 2025

Choose a reason for hiding this comment

Uh oh!

jian-lin Aug 17, 2025

Choose a reason for hiding this comment

Uh oh!

michaelpj Aug 17, 2025

Choose a reason for hiding this comment

Uh oh!

jian-lin Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jian-lin Aug 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jian-lin commented Jun 8, 2025 •

edited

Loading

jian-lin commented Aug 7, 2025 •

edited

Loading

jian-lin Aug 7, 2025 •

edited

Loading

jian-lin Aug 21, 2025 •

edited

Loading