[GHC] #12372: bug: documentation for Control.Monad.guard not useful after AMP

[GHC]

#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