Improve documentation for Control.Monad.State

[mars0i]

The documentation for State in Control.Monad.State gives State's type definition as as type StateT s Identity, and says that "The State monad is a synonym for the StateT monad transformer, applied to the Identity monad."

That documentation simply repeats whats' in the type signature, but I have to assume that I'm not alone in finding the type signature opaque. Understanding it requires studying StateT and Identity, and then figuring out what the implications of their combination are.

There's information that seems relevant in the documentation for MonadState in Control.Monad.State.Class, but it's not easy to figure out what the relationship is between MonadState and StateT s Identity. It doesn't seem as if one is normally supposed to use MonadState directly, in any event.

Purescript by Example has some discussion of the State monad. It's helpful, but it's fairly superficial and didn't answer my questions. I didn't find anything helpful for my needs in Jordan's Reference, though it's possible that I haven't looked in the right place. Instead I've been studying Haskell resources to learn about Haskell's Control.Monad.State, which is obviously the model for Purescript's State. However, then one has to worry about possible differences in corner cases or even more substantial semantical features. This becomes a real issue when I translate Haskell code into Purescript and get an error that isn't due to obvious differences between the languages. (e.g. it's obvioius using (x, y) instead of Tuple x y is a mistake). Then it's not clear whether I made a mistake, or whether there's difference in the semantics of the two State monads. Since it's hard to understand the documentation for Purescript's State, figuring out whether there's a difference isn't easy. (The documentation for Haskell's State is confusing, too, but the docs are more detailed, and there are lots of other things one can read about Haskell's State.)

Normally, I'd expect that more explanation of something like the State monad might be found in the package documentation. However, since the Control.Monad.* modules are part of the transformers package, and there are lots of other modules in that package, I can understand why the package documentation doesn't say anything about particular modules or groups of modules.

However, I think there needs to be documentation of State that goes beyond it's type alias definition. One small thing that might help would be a brief explanation within the documentation for State of its relationship to MonadState.

Thanks!