Skip to content

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 to f :: forall a. a->a, assuming a 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?

To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information