#12372: bug: documentation for Control.Monad.guard not useful after AMP -------------------------------------+------------------------------------- Reporter: ntc2 | Owner: Type: bug | Status: new Priority: normal | Milestone: Component: | Version: 8.0.1 libraries/base | Keywords: | Operating System: Unknown/Multiple Architecture: | Type of failure: Documentation Unknown/Multiple | bug Test Case: | Blocked By: Blocking: | Related Tickets: Differential Rev(s): | Wiki Page: -------------------------------------+------------------------------------- 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 -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/12372 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler