Skip to content

Commit 03088ee

Browse files
committed
Document Ide.Plugin.ConfigUtils
1 parent 8106ea4 commit 03088ee

File tree

1 file changed

+43
-4
lines changed

1 file changed

+43
-4
lines changed

hls-plugin-api/src/Ide/Plugin/ConfigUtils.hs

Lines changed: 43 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,18 @@ import Ide.Plugin.Properties (toDefaultJSON, toVSCodeExtensionSchema)
1717
import Ide.Types
1818
import Language.LSP.Types
1919

20+
-- Attention:
21+
-- 'diagnosticsOn' will never be added into the default config or the schema,
22+
-- since diagnostics emit in arbitrary shake rules -- we don't know
23+
-- whether a plugin is capable of producing diagnostics.
24+
25+
-- | Generates a defalut 'Config', but remains only effective items
2026
pluginsToDefaultConfig :: IdePlugins a -> A.Value
2127
pluginsToDefaultConfig IdePlugins {..} =
2228
A.Object $
2329
HMap.adjust
2430
( \(unsafeValueToObject -> o) ->
25-
A.Object $ HMap.insert "plugin" elems o
31+
A.Object $ HMap.insert "plugin" elems o -- inplace the "plugin" section with our 'elems', leaving others unchanged
2632
)
2733
"haskell"
2834
(unsafeValueToObject (A.toJSON defaultConfig))
@@ -31,25 +37,56 @@ pluginsToDefaultConfig IdePlugins {..} =
3137
unsafeValueToObject (A.Object o) = o
3238
unsafeValueToObject _ = error "impossible"
3339
elems = A.object $ mconcat $ singlePlugin <$> Map.elems ipMap
40+
-- Splice genericDefaultConfig and dedicatedDefaultConfig
41+
-- Example:
42+
--
43+
-- {
44+
-- "plugin-id": {
45+
-- "globalOn": true,
46+
-- "codeActionsOn": true,
47+
-- "codeLensOn": true,
48+
-- "config": {
49+
-- "property1": "foo"
50+
-- }
51+
-- }
52+
-- }
3453
singlePlugin PluginDescriptor {..} =
35-
let x = geenericDefaultConfig <> dedicatedDefaultConfig
54+
let x = genericDefaultConfig <> dedicatedDefaultConfig
3655
in [pId A..= A.object x | not $ null x]
3756
where
3857
(PluginHandlers (DMap.toList -> handlers)) = pluginHandlers
3958
customConfigToDedicatedDefaultConfig (CustomConfig p) = toDefaultJSON p
59+
-- Example:
60+
--
61+
-- {
62+
-- "globalOn": true,
63+
-- "codeActionsOn": true,
64+
-- "codeLensOn": true
65+
-- }
66+
--
4067
-- we don't generate the config section if the plugin doesn't register any of the following six methods,
41-
-- which avoids producing redundant configuration for formatters:
68+
-- which avoids producing trivial configuration for formatters:
4269
--
4370
-- "stylish-haskell": {
4471
-- "globalOn": true
4572
-- }
46-
geenericDefaultConfig =
73+
genericDefaultConfig =
4774
let x = mconcat (handlersToGenericDefaultConfig <$> handlers)
4875
in ["globalOn" A..= True | not $ null x] <> x
76+
-- Example:
77+
--
78+
-- {
79+
-- "config": {
80+
-- "property1": "foo"
81+
-- }
82+
--}
4983
dedicatedDefaultConfig =
5084
let x = customConfigToDedicatedDefaultConfig pluginCustomConfig
5185
in ["config" A..= A.object x | not $ null x]
86+
5287
(PluginId pId) = pluginId
88+
89+
-- This function captures ide methods registered by the plugin, and then converts it to kv pairs
5390
handlersToGenericDefaultConfig :: DSum.DSum IdeMethod f -> [A.Pair]
5491
handlersToGenericDefaultConfig (IdeMethod m DSum.:=> _) = case m of
5592
STextDocumentCodeAction -> ["codeActionsOn" A..= True]
@@ -60,6 +97,8 @@ pluginsToDefaultConfig IdePlugins {..} =
6097
STextDocumentCompletion -> ["completionOn" A..= True]
6198
_ -> []
6299

100+
-- | Generates json schema used in haskell vscode extension
101+
-- Similar to 'pluginsToDefaultConfig' but simpler, since schema has a flatten structure
63102
pluginsToVSCodeExtensionSchema :: IdePlugins a -> A.Value
64103
pluginsToVSCodeExtensionSchema IdePlugins {..} = A.object $ mconcat $ singlePlugin <$> Map.elems ipMap
65104
where

0 commit comments

Comments
 (0)