bug: documentation for Control.Monad.guard not useful after AMP
Since the AMP refactor, the documentation for Control.Monad.guard [1] is no longer useful for beginners. It simply gives the definition of guard, but in prose:
guard b is pure () if b is True, and empty if b is False.(and better to just use Haskell instead of prose here, no?)
To use guard in a MonadPlus, you now need to know that Alternative is a super class of MonadPlus, and that mzero = zero. The documentation [2] for MonadPlus doens't mention mzero = zero in the default definition -- you must look at the source for that -- and the docs for guard don't mention MonadPlus.
The documentation for Control.Monad.guard should suggest use with MonadPlus, and give an example (compare with the very helpful example for Control.Monad.when). A non-monadic example would also be useful.
[1] https://hackage.haskell.org/package/base-4.9.0.0/docs/Control-Monad.html#v:guard
[2] https://hackage.haskell.org/package/base-4.9.0.0/docs/Control-Monad.html#t:MonadPlus
Trac metadata
| Trac field | Value |
|---|---|
| Version | 8.0.1 |
| Type | Bug |
| TypeOfFailure | OtherFailure |
| Priority | normal |
| Resolution | Unresolved |
| Component | libraries/base |
| Test case | |
| Differential revisions | |
| BlockedBy | |
| Related | |
| Blocking | |
| CC | |
| Operating system | |
| Architecture |