Add documentation

Fix ambiguous plugin handler use
haskell · Jun 13, 2022 · f514d2e · f514d2e
1 parent e95a904
commit f514d2e
Show file tree

Hide file tree

Showing 3 changed files with 18 additions and 6 deletions.
diff --git a/ghcide/src/Development/IDE/LSP/Server.hs b/ghcide/src/Development/IDE/LSP/Server.hs
@@ -18,7 +18,7 @@ module Development.IDE.LSP.Server
 import           Control.Monad.Reader
 import           Development.IDE.Core.Shake
 import           Development.IDE.Core.Tracing
-import           Ide.Types                    (HasTracing, traceWithSpan, PluginRequestMethod, PluginNotificationMethod)
+import           Ide.Types                    (HasTracing, traceWithSpan)
 import           Language.LSP.Server          (Handlers, LspM)
 import qualified Language.LSP.Server          as LSP
 import           Language.LSP.Types

diff --git a/hls-plugin-api/src/Ide/Types.hs b/hls-plugin-api/src/Ide/Types.hs
@@ -119,7 +119,11 @@ data PluginDescriptor (ideState :: *) =
                    , pluginNotificationHandlers :: PluginNotificationHandlers ideState
                    , pluginModifyDynflags :: DynFlagsModifications
                    , pluginCli            :: Maybe (ParserInfo (IdeCommand ideState))
-                   , pluginFileType       :: [T.Text]
+                   , pluginFileType       :: [T.Text] 
+                   -- ^ File extension of the files the plugin is responsible for.  
+                   --   The plugin is only allowed to handle files with these extensions
+                   --   When writing handlers, etc. for this plugin it can be assumed that all handled files are of this type.
+                   --   The file extension must have a leading '.'.
                    }
 
 -- | An existential wrapper of 'Properties'
@@ -165,7 +169,13 @@ defaultConfigDescriptor = ConfigDescriptor True False (mkCustomConfig emptyPrope
 class HasTracing (MessageParams m) => PluginMethod (k :: MethodType) (m :: Method FromClient k) where
 
   -- | Parse the configuration to check if this plugin is enabled
-  pluginEnabled :: SMethod m -> MessageParams m -> PluginDescriptor c -> Config -> Bool
+  pluginEnabled 
+    :: SMethod m 
+    -> MessageParams m
+    -- ^ 
+    -> PluginDescriptor c 
+    -> Config 
+    -> Bool
 
   default pluginEnabled :: (HasTextDocument (MessageParams m) doc, HasUri doc Uri)
                               => SMethod m -> MessageParams m -> PluginDescriptor c -> Config -> Bool
@@ -220,6 +230,9 @@ instance PluginRequestMethod TextDocumentCodeAction where
         , Just caKind <- ca ^. kind = any (\k -> k `codeActionKindSubsumes` caKind) allowed
         | otherwise = False
 
+-- | Check whether the given plugin descriptor is responsible for the file with the given path.
+--   Compares the file extension of the file at the given path with the file extension 
+--   the plugin is responsible for.
 pluginResponsible :: Uri -> PluginDescriptor c -> Bool
 pluginResponsible uri pluginDesc
     | Just fp <- mfp

diff --git a/plugins/default/src/Ide/Plugin/ExampleCabal.hs b/plugins/default/src/Ide/Plugin/ExampleCabal.hs
@@ -1,6 +1,5 @@
 {-# LANGUAGE DeriveAnyClass        #-}
 {-# LANGUAGE DeriveGeneric         #-}
-{-# LANGUAGE DuplicateRecordFields #-}
 {-# LANGUAGE FlexibleContexts      #-}
 {-# LANGUAGE FlexibleInstances     #-}
 {-# LANGUAGE LambdaCase            #-}
@@ -15,7 +14,7 @@ module Ide.Plugin.ExampleCabal where
 import           Control.Monad.IO.Class
 import           Data.Aeson
 import qualified Data.Text as T
-import           Development.IDE            as D
+import           Development.IDE            as D hiding (pluginHandlers)
 import           GHC.Generics
 import           Ide.PluginUtils
 import           Ide.Types
@@ -29,7 +28,7 @@ instance Pretty Log where
     LogText log -> pretty log
 
 descriptor :: Recorder (WithPriority Log) -> PluginId -> PluginDescriptor IdeState
-descriptor recorder plId = (defaultCabalPluginDescriptor plId)
+descriptor recorder plId = (defaultCabalPluginDescriptor plId :: PluginDescriptor IdeState)
   { pluginHandlers = mkPluginHandler STextDocumentCodeLens       (codeLens recorder)
   }