Add more documentation for formatters

Author: fendor

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

@@ -208,9 +208,20 @@ 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
                     | FormatRange Range
-type FormattingProvider = Uri -> FormattingType -> FormattingOptions -> IdeDeferM (IdeResult [TextEdit])
+
+-- |Formats the given Uri with the given options.
+-- A formatting type can be given to either format the whole documetn or only a Range.
+-- Fails if the formatter can not parse the source.
+-- Failing menas 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.
+type FormattingProvider = Uri -- ^ Uri to the file to format. Can be mapped to a file with `pluginGetFile`
+        -> FormattingType  -- ^ How much to format
+        -> FormattingOptions -- ^ Options for the formatter
+        -> IdeDeferM (IdeResult [TextEdit]) -- ^ Result of the formatting or the unchanged text.
 
 data PluginDescriptor =
   PluginDescriptor { pluginId                 :: PluginId

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

@@ -36,6 +36,9 @@ brittanyDescriptor plId = PluginDescriptor
   , pluginFormattingProvider = Just provider
   }
 
+-- |Formatter provider of Brittany.
+-- Formats the given source in either a given Range or the whole Document.
+-- If the provider fails an error is returned that can be displayed to the user.
 provider :: FormattingProvider
 provider uri formatType opts = pluginGetFile "brittanyCmd: " uri $ \file -> do
   confFile <- liftIO $ getConfFile file
@@ -65,6 +68,8 @@ normalize (Range (Position sl _) (Position el _)) =
   -- Extend to the line below to replace newline character, as above
   Range (Position sl 0) (Position (el + 1) 0)
 
+-- |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
 

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

@@ -27,6 +27,9 @@ floskellDescriptor plId = PluginDescriptor
   , pluginFormattingProvider = Just provider
   }
 
+-- |Format provider of Floskell.
+-- Formats the given source in either a given Range or the whole Document.
+-- If the provider fails an error is returned that can be displayed to the user.
 provider :: FormattingProvider
 provider uri typ _opts =
   pluginGetFile "Floskell: " uri $ \file -> do
@@ -43,8 +46,10 @@ provider uri typ _opts =
               Left  err -> return $ IdeResultFail (IdeError PluginError (T.pack err) Null)
               Right new -> return $ IdeResultOk [TextEdit range (T.decodeUtf8 (BS.toStrict new))]
 
-
-
+-- |Find Floskell Config, user and system wide or provides a default style.
+-- Every directory of the filepath will be searched to find a user configuration.
+-- Also looks into places such as XDG_CONFIG_DIRECTORY<https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>.
+-- This function may not throw an exception and returns a default config.
 findConfigOrDefault :: FilePath -> IO AppConfig
 findConfigOrDefault file = do
   mbConf <- findAppConfigIn file