Docs: checkParents options

[andys8]

Hey there, I was looking up what options are possible for the checkParents configuration, and there seems to be a mismatch in several places. Maybe we can find out what is correct and adapt all places mentioned.

Default config

Output of haskell-language-server-wrapper generate-default-config is "checkParents": "CheckOnSave"

Documentation

• Missing CheckOnSave
• Has CheckOnSaveAndClose

Check parents (haskell.checkParents, default CheckOnSaveAndClose): when to typecheck reverse dependencies of a file; one of NeverCheck, CheckOnClose, CheckOnSaveAndClose, or AlwaysCheck.

GHCIDE README

• Says "CheckOnSave means dependent/parent modules will only be checked when you save"
• Options don't include CheckOnSave but CheckOnClose and CheckOnSaveAndClose
• There is a dangling | ,

https://github.com/haskell/haskell-language-server/blob/0c5a317560c4ee7257ddf03de117868cb7a056c2/ghcide/README.md#configuration

Types

The CheckParents type only seems to have CheckOnSave and is also used as Aeson instance.

haskell-language-server/hls-plugin-api/src/Ide/Plugin/Config.hs

Lines 36 to 43 in 310e6a4

	data CheckParents
	-- Note that ordering of constructors is meaningful and must be monotonically
	-- increasing in the scenarios where parents are checked
	= NeverCheck
	| CheckOnSave
	| AlwaysCheck
	deriving stock (Eq, Ord, Show, Generic)
	deriving anyclass (FromJSON, ToJSON)

Your environment

haskell-language-server-wrapper generate-default-config

Found "/home/andreas/dev/work/project/hie.yaml" for "/home/andreas/dev/work/project/a"
Run entered for haskell-language-server-wrapper(haskell-language-server-wrapper) Version 1.8.0.0 x86_64 ghc-9.2.4
Current directory: /home/andreas/dev/work/project
Operating system: linux
Arguments: ["generate-default-config"]
Cradle directory: /home/andreas/dev/work/project
Cradle type: Stack

Tool versions found on the $PATH
cabal:          3.8.1.0
stack:          2.7.5
ghc:            9.2.4


Consulting the cradle to get project GHC version...
Project GHC version: 8.10.7
haskell-language-server exe candidates: ["haskell-language-server-8.10.7","haskell-language-server"]
Launching haskell-language-server exe at:/home/andreas/.ghcup/bin/haskell-language-server-8.10.7
2022-09-14T10:18:56.286445Z | Info | No log file specified; using stderr.
2022-09-14T10:18:56.290215Z | Info | haskell-language-server version: 1.8.0.0 (GHC: 8.10.7) (PATH: /home/andreas/.ghcup/bin/haskell-language-server-8.10.7~1.8.0.0)
2022-09-14T10:18:56.291014Z | Info | Directory: /home/andreas/dev/work/project
2022-09-14T10:18:56.291967Z | Info | Logging heap statistics every 60.00s
 {
    "haskell": {
        "checkParents": "CheckOnSave",
        "checkProject": true,
        "maxCompletions": 40,
        "formattingProvider": "ormolu",
        "plugin": {
            "rename": {
                "globalOn": true,
                "config": {
                    "crossModule": false
                }
            },
            "ghcide-completions": {
                "globalOn": true,
                "config": {
                    "autoExtendOn": true,
                    "snippetsOn": true
                }
            },
            "class": {
                "codeActionsOn": true,
                "codeLensOn": true
            },
            "refineImports": {
                "codeActionsOn": true,
                "codeLensOn": true
            },
            "splice": {
                "globalOn": true
            },
            "pragmas": {
                "completionOn": true,
                "codeActionsOn": true
            },
            "changeTypeSignature": {
                "globalOn": true
            },
            "qualifyImportedNames": {
                "globalOn": true
            },
            "alternateNumberFormat": {
                "globalOn": true
            },
            "hlint": {
                "codeActionsOn": true,
                "diagnosticsOn": true,
                "config": {
                    "flags": []
                }
            },
            "ghcide-code-actions-fill-holes": {
                "globalOn": true
            },
            "explicitFixity": {
                "globalOn": true
            },
            "haddockComments": {
                "globalOn": true
            },
            "importLens": {
                "codeActionsOn": true,
                "codeLensOn": true
            },
            "retrie": {
                "globalOn": true
            },
            "ghcide-type-lenses": {
                "globalOn": true,
                "config": {
                    "mode": "always"
                }
            },
            "ghcide-code-actions-imports-exports": {
                "globalOn": true
            },
            "ghcide-hover-and-symbols": {
                "symbolsOn": true,
                "hoverOn": true
            },
            "eval": {
                "globalOn": true,
                "config": {
                    "diff": true,
                    "exception": false
                }
            },
            "gadt": {
                "globalOn": true
            },
            "tactics": {
                "codeActionsOn": true,
                "codeLensOn": true,
                "hoverOn": true,
                "config": {
                    "auto_gas": 4,
                    "max_use_ctor_actions": 5,
                    "proofstate_styling": true,
                    "timeout_duration": 2,
                    "hole_severity": null
                }
            },
            "callHierarchy": {
                "globalOn": true
            },
            "ghcide-code-actions-type-signatures": {
                "globalOn": true
            },
            "ghcide-code-actions-bindings": {
                "globalOn": true
            },
            "moduleName": {
                "globalOn": true
            }
        }
    }
}

[michaelpj]

It would be lovely if we could auto-generate some documentation about the options... there are too many for us to not make mistakes like this.

[andys8]

My assumption is that the types don't lie and only these 3 values are possible. Who could provide information what the current state of truth is or provide some context?

haskell-language-server/hls-plugin-api/src/Ide/Plugin/Config.hs

Lines 36 to 43 in 310e6a4

	data CheckParents
	-- Note that ordering of constructors is meaningful and must be monotonically
	-- increasing in the scenarios where parents are checked
	= NeverCheck
	| CheckOnSave
	| AlwaysCheck
	deriving stock (Eq, Ord, Show, Generic)
	deriving anyclass (FromJSON, ToJSON)

[pepeiborra]

Check on close modes were removed because they interacted badly with garbage collection.

[michaelpj]

I suggest removing this information from the ghcide readme and moving it to the main documentation also? Maintaining multiple places is even more error-prone!

[andys8]

Okay, then it's an easy change: #3184

While I do think generation of docs would be appreciated, in this case #3183 wouldn't have helped, since the outdated information is not related to plugins. But in general coupling documentation and implementation - could also be used in error messages and on CLI - in a way that prevents outdated information like this would be very cool.