Document and rename formatting type options.

Author: fendor

hie-plugin-api/Haskell/Ide/Engine/PluginsIdeMonads.hs

@@ -207,15 +207,18 @@ type HoverProvider = Uri -> Position -> IdeM (IdeResult [Hover])
 
 type SymbolProvider = Uri -> IdeDeferM (IdeResult [DocumentSymbol])
 
--- | Format the document either as a whole or only a given Range of it.
-data FormattingType = FormatDocument
+-- | Format the given Text as a whole or only a @Range@ of it.
+-- Range must be relative to the text to format.
+-- To format the whole document, read the Text from the file and use 'FormatText'
+-- as the FormattingType.
+data FormattingType = FormatText
                     | FormatRange Range
 
 -- | Formats the given Text associated with the given Uri.
--- Should, but might not, honor the provided formatting options (e.g. Floskell does not).
--- A formatting type can be given to either format the whole document or only a Range.
--- 
--- Text to format, may or may not, originate from the associated Uri. 
+-- Should, but might not, honour the provided formatting options (e.g. Floskell does not).
+-- A formatting type can be given to either format the whole text or only a Range.
+--
+-- Text to format, may or may not, originate from the associated Uri.
 -- E.g. it is ok, to modify the text and then reformat it through this API.
 --
 -- The Uri is mainly used to discover formatting configurations in the file's path.
@@ -224,6 +227,11 @@ data FormattingType = FormatDocument
 -- Failing means here that a IdeResultFail is returned.
 -- This can be used to display errors to the user, unless the error is an Internal one.
 -- The record 'IdeError' and 'IdeErrorCode' can be used to determine the type of error.
+--
+--
+-- To format a whole document, the 'FormatText' @FormattingType@ can be used.
+-- It is required to pass in the whole Document Text for that to happen, an empty text
+-- and file uri, does not suffice.
 type FormattingProvider = T.Text -- ^ Text to format
         -> Uri -- ^ Uri of the file being formatted
         -> FormattingType  -- ^ How much to format

src/Haskell/Ide/Engine/Plugin/Brittany.hs

@@ -43,8 +43,8 @@ provider
 provider text uri formatType opts = pluginGetFile "brittanyCmd: " uri $ \fp -> do
   confFile <- liftIO $ getConfFile fp
   let (range, selectedContents) = case formatType of
-        FormatDocument -> (fullRange text, text)
-        FormatRange r  -> (normalize r, extractRange r text)
+        FormatText    -> (fullRange text, text)
+        FormatRange r -> (normalize r, extractRange r text)
 
   res <- formatText confFile opts selectedContents
   case res of
@@ -70,16 +70,23 @@ formatText confFile opts text =
   liftIO $ runBrittany tabSize confFile text
   where tabSize = opts ^. J.tabSize
 
--- | Extend to the line below to replace newline character, as above.
+-- | Extend to the line below and above to replace newline character.
 normalize :: Range -> Range
 normalize (Range (Position sl _) (Position el _)) =
   Range (Position sl 0) (Position (el + 1) 0)
 
--- | Recursively search in every directory of the given filepath for brittany.yaml
+-- | Recursively search in every directory of the given filepath for brittany.yaml.
 -- If no such file has been found, return Nothing.
 getConfFile :: FilePath -> IO (Maybe FilePath)
 getConfFile = findLocalConfigPath . takeDirectory
 
+-- | Run Brittany on the given text with the given tab size and
+-- a configuration path. If no configuration path is given, a
+-- default configuration is chosen. The configuration may overwrite
+-- tab size parameter.
+--
+-- Returns either a list of Brittany Errors or the reformatted text.
+-- May not throw an exception.
 runBrittany :: Int              -- ^ tab  size
             -> Maybe FilePath   -- ^ local config file
             -> Text             -- ^ text to format

src/Haskell/Ide/Engine/Plugin/Floskell.hs

@@ -35,8 +35,8 @@ provider contents uri typ _opts =
   pluginGetFile "Floskell: " uri $ \file -> do
     config <- liftIO $ findConfigOrDefault file
     let (range, selectedContents) = case typ of
-          FormatDocument -> (fullRange contents, contents)
-          FormatRange r  -> (r, extractRange r contents)
+          FormatText    -> (fullRange contents, contents)
+          FormatRange r -> (r, extractRange r contents)
         result = reformat config (Just file) (BS.fromStrict (T.encodeUtf8 selectedContents))
     case result of
       Left  err -> return $ IdeResultFail (IdeError PluginError (T.pack $  "floskellCmd: " ++ err) Null)

src/Haskell/Ide/Engine/Plugin/HsImport.hs

@@ -58,6 +58,9 @@ importCmd = CmdSync $ \(ImportParams uri importList modName) ->
 
 -- | Import the given module for the given file.
 -- May take an explicit function name to perform an import-list import.
+-- Multiple import-list imports will result in merged imports,
+-- e.g. two consecutive imports for the same module will result in a single
+-- import line.
 importModule
   :: Uri -> Maybe T.Text -> T.Text -> IdeGhcM (IdeResult J.WorkspaceEdit)
 importModule uri importList modName =
@@ -75,33 +78,39 @@ importModule uri importList modName =
                              , symbolName    = T.unpack $ fromMaybe "" importList
                              , outputSrcFile = output
                              }
+      -- execute hsimport on the given file and write into a temporary file.
       maybeErr <- liftIO $ hsimportWithArgs defaultConfig args
       case maybeErr of
         Just err -> do
           liftIO $ removeFile output
           let msg = T.pack $ show err
           return $ IdeResultFail (IdeError PluginError msg Null)
         Nothing -> do
+          -- Since no error happened, calculate the differences of
+          -- the original file and after the import has been done.
           newText <- liftIO $ T.readFile output
           liftIO $ removeFile output
           J.WorkspaceEdit mChanges mDocChanges <- liftToGhc
             $ makeDiffResult input newText fileMap
 
+          -- If the client wants its import formatted,
+          -- it can be configured in the config.
           if shouldFormat
             then do
               config  <- getConfig
               plugins <- getPlugins
               let mprovider = Hie.getFormattingPlugin config plugins
               case mprovider of
+                -- Client may have no formatter selected
+                -- but still the option to format on import.
                 Nothing ->
                   return $ IdeResultOk (J.WorkspaceEdit mChanges mDocChanges)
 
                 Just (_, provider) -> do
                   let formatEdit :: J.TextEdit -> IdeGhcM J.TextEdit
                       formatEdit origEdit@(J.TextEdit r t) = do
-                        let strippedText = T.dropWhileEnd (=='\n') t
                         -- TODO: are these default FormattingOptions ok?
-                        res <- liftToGhc $ provider strippedText uri FormatDocument (FormattingOptions 2 True)
+                        res <- liftToGhc $ provider t uri FormatText (FormattingOptions 2 True)
                         let formatEdits = case res of
                                             IdeResultOk xs -> xs
                                             _ -> [origEdit]

src/Haskell/Ide/Engine/Transport/LspStdio.hs

@@ -736,7 +736,7 @@ reactor inp diagIn = do
               doc = params ^. J.textDocument . J.uri
           withDocumentContents (req ^. J.id) doc $ \text ->
             let callback = reactorSend . RspDocumentFormatting . Core.makeResponseMessage req . J.List
-                hreq = IReq tn (req ^. J.id) callback $ lift $ provider text doc FormatDocument (params ^. J.options)
+                hreq = IReq tn (req ^. J.id) callback $ lift $ provider text doc FormatText (params ^. J.options)
               in makeRequest hreq
 
         -- -------------------------------
@@ -809,10 +809,10 @@ reactor inp diagIn = do
 -- ---------------------------------------------------------------------
 
 -- | Execute a function in the current request with an Uri.
--- Reads the content of the file specified by the Uri and invokes 
+-- Reads the content of the file specified by the Uri and invokes
 -- the function on it.
 --
--- If the Uri can not be mapped to a real file, the function will 
+-- If the Uri can not be mapped to a real file, the function will
 -- not be executed and an error message will be sent to the client.
 -- Error message is associated with the request id and, thus, identifiable.
 withDocumentContents :: J.LspId -> J.Uri -> (T.Text -> R ()) -> R ()
@@ -830,9 +830,9 @@ withDocumentContents reqId uri f = do
 
 -- | Get the currently configured formatter provider.
 -- The currently configured formatter provider is defined in @Config@ by PluginId.
--- 
+--
 -- It is possible that formatter configured by the user is not present.
--- In this case, a nop (No-Operation) formatter is returned and a message will 
+-- In this case, a nop (No-Operation) formatter is returned and a message will
 -- be sent to the user.
 getFormattingProvider :: R FormattingProvider
 getFormattingProvider = do
@@ -847,7 +847,7 @@ getFormattingProvider = do
       unless (providerName == "none") $ do
         let msg = providerName <> " is not a recognised plugin for formatting. Check your config"
         reactorSend $ NotShowMessage $ fmServerShowMessageNotification J.MtWarning msg
-        reactorSend $ NotLogMessage $ fmServerLogMessageNotification J.MtWarning msg    
+        reactorSend $ NotLogMessage $ fmServerLogMessageNotification J.MtWarning msg
       return (\_ _ _ _ -> return (IdeResultOk [])) -- nop formatter
     Just (_, provider) -> return provider