Please clarify "Let-generalisation" MonoLocalBinds documentation
Summary
I found the documentation for MonoLocalBinds [currently on master
] rather difficult to understand. I wonder if it could be clarified.
Proposed improvements or changes
As someone with no experience of the relevant terminology I found the notions of "closed", "generalised" and "fully generalised" hard to grasp. My current understanding is that "closed" refers to a property that a variable may or may not have whereas "generalised" refers to an action that may or may not be performed upon a binding group. That is, "closed" is an adjective and "generalised" is a verb. Is that right?
If so then I would say that the nature of those words is hard to deduce from the text alone. Perhaps we could change
A variable is closed if and only if
to
A variable is called "closed" if and only if
(to indicate that "closed" is an adjective describing the variable, not a verb that is performed on the variable) and
With
MonoLocalBinds
, a binding group is generalised if and only if
to
With
MonoLocalBinds
, a binding group will be generalised if and only if
(to indicate that "generalised" is a verb that is performed on the binding group, not an adjective describing the binding group). I am not strongly wedded to these particular suggestions. There could also be a much better way of clarifying this issue. I do think, though, that it is really important to draw the distinction between adjectives and verbs so that mere mortals like myself can understand this documentation.
Additionally
-
Is there difference between "fully generalised" and "generalised"? If so then could the difference be clarified? If not then could we choose one of the two and use it uniformly?
-
What does "imported" mean? It is mentioned only once on that page. Does it literally mean imported from another module? In any case, could it be clarified?
-
Later on in the file appears
Note that a signature like
f :: a -> a
is equivalent tof :: forall a. a->a
, assuminga
is not in scope, and hence is closed.This sentence applies "closed" to a signature but previously the notion was only defined for variables. Should the text say "and hence
f
is closed" or is there some other meaning?