Regularize custom config of plugins

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

@@ -17,12 +17,18 @@ import           Ide.Plugin.Properties (toDefaultJSON, toVSCodeExtensionSchema)
 import           Ide.Types
 import           Language.LSP.Types
 
+-- Attention:
+-- 'diagnosticsOn' will never be added into the default config or the schema,
+-- since diagnostics emit in arbitrary shake rules -- we don't know
+-- whether a plugin is capable of producing diagnostics.
+
+-- | Generates a defalut 'Config', but remains only effective items
 pluginsToDefaultConfig :: IdePlugins a -> A.Value
 pluginsToDefaultConfig IdePlugins {..} =
   A.Object $
     HMap.adjust
       ( \(unsafeValueToObject -> o) ->
-          A.Object $ HMap.insert "plugin" elems o
+          A.Object $ HMap.insert "plugin" elems o -- inplace the "plugin" section with our 'elems', leaving others unchanged
       )
       "haskell"
       (unsafeValueToObject (A.toJSON defaultConfig))
@@ -31,25 +37,56 @@ pluginsToDefaultConfig IdePlugins {..} =
     unsafeValueToObject (A.Object o) = o
     unsafeValueToObject _            = error "impossible"
     elems = A.object $ mconcat $ singlePlugin <$> Map.elems ipMap
+    -- Splice genericDefaultConfig and dedicatedDefaultConfig
+    -- Example:
+    --
+    -- {
+    --  "plugin-id": {
+    --    "globalOn": true,
+    --    "codeActionsOn": true,
+    --    "codeLensOn": true,
+    --    "config": {
+    --      "property1": "foo"
+    --     }
+    --   }
+    -- }
     singlePlugin PluginDescriptor {..} =
-      let x = geenericDefaultConfig <> dedicatedDefaultConfig
+      let x = genericDefaultConfig <> dedicatedDefaultConfig
        in [pId A..= A.object x | not $ null x]
       where
         (PluginHandlers (DMap.toList -> handlers)) = pluginHandlers
         customConfigToDedicatedDefaultConfig (CustomConfig p) = toDefaultJSON p
+        -- Example:
+        --
+        -- {
+        --   "globalOn": true,
+        --   "codeActionsOn": true,
+        --   "codeLensOn": true
+        -- }
+        --
         -- we don't generate the config section if the plugin doesn't register any of the following six methods,
-        -- which avoids producing redundant configuration for formatters:
+        -- which avoids producing trivial configuration for formatters:
         --
         -- "stylish-haskell": {
         --    "globalOn": true
         -- }
-        geenericDefaultConfig =
+        genericDefaultConfig =
           let x = mconcat (handlersToGenericDefaultConfig <$> handlers)
            in ["globalOn" A..= True | not $ null x] <> x
+        -- Example:
+        --
+        -- {
+        --  "config": {
+        --      "property1": "foo"
+        --   }
+        --}
         dedicatedDefaultConfig =
           let x = customConfigToDedicatedDefaultConfig pluginCustomConfig
            in ["config" A..= A.object x | not $ null x]
+
         (PluginId pId) = pluginId
+
+        -- This function captures ide methods registered by the plugin, and then converts it to kv pairs
         handlersToGenericDefaultConfig :: DSum.DSum IdeMethod f -> [A.Pair]
         handlersToGenericDefaultConfig (IdeMethod m DSum.:=> _) = case m of
           STextDocumentCodeAction     -> ["codeActionsOn" A..= True]
@@ -60,6 +97,8 @@ pluginsToDefaultConfig IdePlugins {..} =
           STextDocumentCompletion     -> ["completionOn" A..= True]
           _                           -> []
 
+-- | Generates json schema used in haskell vscode extension
+-- Similar to 'pluginsToDefaultConfig' but simpler, since schema has a flatten structure
 pluginsToVSCodeExtensionSchema :: IdePlugins a -> A.Value
 pluginsToVSCodeExtensionSchema IdePlugins {..} = A.object $ mconcat $ singlePlugin <$> Map.elems ipMap
   where