Implement signature help (#4626)

Author: jian-lin

.github/workflows/test.yml

@@ -261,6 +261,10 @@ jobs:
         name: Compile the plugin-tutorial
         run: cabal build plugin-tutorial
 
+      - if: matrix.test
+        name: Test hls-signature-help-plugin test suite
+        run: cabal test hls-signature-help-plugin-tests || cabal test hls-signature-help-plugin-tests
+
   test_post_job:
     if: always()
     runs-on: ubuntu-latest

CODEOWNERS

@@ -37,6 +37,7 @@
 /plugins/hls-rename-plugin
 /plugins/hls-retrie-plugin @wz1000
 /plugins/hls-semantic-tokens-plugin @soulomoon
+/plugins/hls-signature-help-plugin @jian-lin
 /plugins/hls-splice-plugin @konn
 /plugins/hls-stan-plugin @0rphee
 /plugins/hls-stylish-haskell-plugin @michaelpj

docs/configuration.md

@@ -52,7 +52,7 @@ Here is a list of the additional settings currently supported by `haskell-langua
 Plugins have a generic config to control their behaviour. The schema of such config is:
 
 - `haskell.plugin.${pluginName}.globalOn`: usually with default true. Whether the plugin is enabled at runtime or it is not. That is the option you might use if you want to disable completely a plugin.
-  - Actual plugin names are: `ghcide-code-actions-fill-holes`, `ghcide-completions`, `ghcide-hover-and-symbols`, `ghcide-type-lenses`, `ghcide-code-actions-type-signatures`, `ghcide-code-actions-bindings`, `ghcide-code-actions-imports-exports`, `eval`, `moduleName`, `pragmas`, `importLens`, `class`, `hlint`, `retrie`, `rename`, `splice`, `stan`.
+  - Actual plugin names are: `ghcide-code-actions-fill-holes`, `ghcide-completions`, `ghcide-hover-and-symbols`, `ghcide-type-lenses`, `ghcide-code-actions-type-signatures`, `ghcide-code-actions-bindings`, `ghcide-code-actions-imports-exports`, `eval`, `moduleName`, `pragmas`, `importLens`, `class`, `hlint`, `retrie`, `rename`, `splice`, `stan`, `signatureHelp`.
   - So to disable the import lens with an explicit list of module definitions you could set `haskell.plugin.importLens.globalOn: false`
 - `haskell.plugin.${pluginName}.${lspCapability}On`: usually with default true. Whether a concrete plugin capability is enabled.
   - Capabilities are the different ways a lsp server can interact with the editor. The current available capabilities of the server are: `callHierarchy`, `codeActions`, `codeLens`, `diagnostics`, `hover`, `symbols`, `completion`, `rename`.

docs/features.md

@@ -7,6 +7,7 @@ Many of these are standard LSP features, but a lot of special features are provi
 | --------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | [Diagnostics](#diagnostics)                         | `textDocument/publishDiagnostics`                                                                 |
 | [Hovers](#hovers)                                   | `textDocument/hover`                                                                              |
+| [Signature help](#signature-help)                   | `textDocument/signatureHelp`                                                                      |
 | [Jump to definition](#jump-to-definition)           | `textDocument/definition`                                                                         |
 | [Jump to type definition](#jump-to-type-definition) | `textDocument/typeDefinition`                                                                     |
 | [Find references](#find-references)                 | `textDocument/references`                                                                         |
@@ -63,6 +64,12 @@ Provided by: `hls-explicit-fixity-plugin`
 
 Provides fixity information.
 
+## Signature help
+
+Provided by: `hls-signature-help-plugin`
+
+Shows and highlights the function signature, the function documentation and the arguments documentation when the cursor is at a function argument.
+
 ## Jump to definition
 
 Provided by: `ghcide`
@@ -445,7 +452,6 @@ 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`                  |
 | Linked editing         | Unimplemented     | `textDocument/linkedEditingRange`              |

docs/support/plugin-support.md

@@ -51,6 +51,7 @@ For example, a plugin to provide a formatter which has itself been abandoned has
 | `hls-class-plugin`                   | 2    |                          |
 | `hls-change-type-signature-plugin`   | 2    |                          |
 | `hls-eval-plugin`                    | 2    |                          |
+| `hls-signature-help-plugin`          | 2    |                          |
 | `hls-explicit-fixity-plugin`         | 2    |                          |
 | `hls-explicit-record-fields-plugin`  | 2    |                          |
 | `hls-fourmolu-plugin`                | 2    |                          |

ghcide/src/Development/IDE/Core/Actions.hs

@@ -63,7 +63,7 @@ getAtPoint file pos = runMaybeT $ do
 
   (hf, mapping) <- useWithStaleFastMT GetHieAst file
   env <- hscEnv . fst <$> useWithStaleFastMT GhcSession file
-  dkMap <- lift $ maybe (DKMap mempty mempty) fst <$> runMaybeT (useWithStaleFastMT GetDocMap file)
+  dkMap <- lift $ maybe (DKMap mempty mempty mempty) fst <$> runMaybeT (useWithStaleFastMT GetDocMap file)
 
   !pos' <- MaybeT (return $ fromCurrentPosition mapping pos)
   MaybeT $ liftIO $ fmap (first (toCurrentRange mapping =<<)) <$> AtPoint.atPoint opts hf dkMap env pos'

ghcide/src/Development/IDE/Core/RuleTypes.hs

@@ -253,9 +253,15 @@ type instance RuleResult GetHieAst = HieAstResult
 -- | A IntervalMap telling us what is in scope at each point
 type instance RuleResult GetBindings = Bindings
 
-data DocAndTyThingMap = DKMap {getDocMap :: !DocMap, getTyThingMap :: !TyThingMap}
+data DocAndTyThingMap = DKMap
+    { getDocMap     :: !DocMap
+    -- ^ Docs for declarations: functions, data types, instances, methods, etc
+    , getTyThingMap :: !TyThingMap
+    , getArgDocMap  :: !ArgDocMap
+    -- ^ Docs for arguments, e.g., function arguments and method arguments
+    }
 instance NFData DocAndTyThingMap where
-    rnf (DKMap a b) = rwhnf a `seq` rwhnf b
+    rnf (DKMap a b c) = rwhnf a `seq` rwhnf b `seq` rwhnf c
 
 instance Show DocAndTyThingMap where
     show = const "docmap"

ghcide/src/Development/IDE/Core/Rules.hs

@@ -582,7 +582,7 @@ getDocMapRule recorder =
 
 -- | Persistent rule to ensure that hover doesn't block on startup
 persistentDocMapRule :: Rules ()
-persistentDocMapRule = addPersistentRule GetDocMap $ \_ -> pure $ Just (DKMap mempty mempty, idDelta, Nothing)
+persistentDocMapRule = addPersistentRule GetDocMap $ \_ -> pure $ Just (DKMap mempty mempty mempty, idDelta, Nothing)
 
 readHieFileForSrcFromDisk :: Recorder (WithPriority Log) -> NormalizedFilePath -> MaybeT IdeAction Compat.HieFile
 readHieFileForSrcFromDisk recorder file = do

ghcide/src/Development/IDE/GHC/Compat/Outputable.hs

@@ -9,6 +9,7 @@ module Development.IDE.GHC.Compat.Outputable (
     ppr, pprPanic, text, vcat, (<+>), ($$), empty, hang, nest, punctuate,
     printSDocQualifiedUnsafe,
     printWithoutUniques,
+    printWithoutUniquesOneLine,
     mkPrintUnqualifiedDefault,
     PrintUnqualified,
     defaultUserStyle,
@@ -27,6 +28,7 @@ module Development.IDE.GHC.Compat.Outputable (
     pprMsgEnvelopeBagWithLoc,
     Error.getMessages,
     renderWithContext,
+    showSDocOneLine,
     defaultSDocContext,
     errMsgDiagnostic,
     unDecorated,
@@ -76,8 +78,14 @@ type PrintUnqualified = NamePprCtx
 --
 -- It print with a user-friendly style like: `a_a4ME` as `a`.
 printWithoutUniques :: Outputable a => a -> String
-printWithoutUniques =
-  renderWithContext (defaultSDocContext
+printWithoutUniques = printWithoutUniques' renderWithContext
+
+printWithoutUniquesOneLine :: Outputable a => a -> String
+printWithoutUniquesOneLine = printWithoutUniques' showSDocOneLine
+
+printWithoutUniques' :: Outputable a => (SDocContext -> SDoc -> String) -> a -> String
+printWithoutUniques' showSDoc =
+  showSDoc (defaultSDocContext
     {
       sdocStyle = defaultUserStyle
     , sdocSuppressUniques = True

ghcide/src/Development/IDE/GHC/Util.hs

@@ -27,6 +27,7 @@ module Development.IDE.GHC.Util(
     dontWriteHieFiles,
     disableWarningsAsErrors,
     printOutputable,
+    printOutputableOneLine,
     getExtensions,
     stripOccNamePrefix,
     ) where
@@ -264,11 +265,17 @@ ioe_dupHandlesNotCompatible h =
 --   1. print with a user-friendly style: `a_a4ME` as `a`.
 --   2. unescape escape sequences of printable unicode characters within a pair of double quotes
 printOutputable :: Outputable a => a -> T.Text
-printOutputable =
+printOutputable = printOutputable' printWithoutUniques
+
+printOutputableOneLine :: Outputable a => a -> T.Text
+printOutputableOneLine = printOutputable' printWithoutUniquesOneLine
+
+printOutputable' :: Outputable a => (a -> String) -> a -> T.Text
+printOutputable' print =
     -- IfaceTyLit from GHC.Iface.Type implements Outputable with 'show'.
     -- Showing a String escapes non-ascii printable characters. We unescape it here.
     -- More discussion at https://github.com/haskell/haskell-language-server/issues/3115.
-    unescape . T.pack . printWithoutUniques
+    unescape . T.pack . print
 {-# INLINE printOutputable #-}
 
 getExtensions :: ParsedModule -> [Extension]